catence 0.0.0 → 0.1.0

package/dist/elt/normalization/segments/strava-normalizer.d.ts

@@ -0,0 +1,3 @@
+import type { CatenceDatabase } from '../../storage/database.js';
+import type { SourceEntity } from '../../../contracts/staging.js';
+export declare function normalizeStravaEntity(database: CatenceDatabase, entity: SourceEntity): Promise<void>;

package/dist/elt/normalization/segments/strava-normalizer.js

@@ -0,0 +1,93 @@
+import { json } from '../../storage/sql.js';
+const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value) ? value : {};
+const text = (value) => typeof value === 'string' && value ? value : typeof value === 'number' ? String(value) : null;
+const number = (value) => typeof value === 'number' && Number.isFinite(value) ? value : typeof value === 'string' && value.trim() !== '' && Number.isFinite(Number(value)) ? Number(value) : null;
+const dateOnly = (value) => typeof value === 'string' && /^\d{4}-\d{2}-\d{2}/.test(value) ? value.slice(0, 10) : null;
+async function storeGenericEntity(database, entity, payload) {
+    await database.run(`INSERT INTO source_entities (provider, entity_type, remote_id, parent_remote_id, occurred_on, source_updated_at, raw_object_hash, payload_json, extension_json)
+    VALUES ('strava', $entityType, $remoteId, $parentRemoteId, $occurredOn, $sourceUpdatedAt, $rawHash, $payload, $extension)
+    ON CONFLICT (provider, entity_type, remote_id) DO UPDATE SET parent_remote_id = excluded.parent_remote_id, occurred_on = excluded.occurred_on, source_updated_at = excluded.source_updated_at, raw_object_hash = excluded.raw_object_hash, payload_json = excluded.payload_json, extension_json = excluded.extension_json, normalized_at = now()`, { entityType: entity.entityType, remoteId: entity.remoteId, parentRemoteId: entity.parentRemoteId, occurredOn: entity.occurredOn, sourceUpdatedAt: entity.sourceUpdatedAt, rawHash: entity.rawObjectHash, payload: json(payload), extension: json(entity.extension) });
+    await database.run(`INSERT INTO domain_entities (provider, entity_type, remote_id, parent_remote_id, occurred_on, payload_json, extension_json, raw_object_hash)
+    VALUES ('strava', $entityType, $remoteId, $parentRemoteId, $occurredOn, $payload, $extension, $rawHash)
+    ON CONFLICT (provider, entity_type, remote_id) DO UPDATE SET parent_remote_id = excluded.parent_remote_id, occurred_on = excluded.occurred_on, payload_json = excluded.payload_json, extension_json = excluded.extension_json, raw_object_hash = excluded.raw_object_hash`, { entityType: entity.entityType, remoteId: entity.remoteId, parentRemoteId: entity.parentRemoteId, occurredOn: entity.occurredOn, rawHash: entity.rawObjectHash, payload: json(payload), extension: json(entity.extension) });
+}
+/** Persist richer segment facts without letting a sparse embedded history effort erase them. */
+async function upsertSegment(database, source, rawHash) {
+    const segmentId = text(source.id);
+    if (!segmentId)
+        return;
+    const hasDescriptiveFacts = text(source.name) !== null || typeof source.starred === 'boolean' || number(source.average_grade) !== null || number(source.distance) !== null;
+    await database.run(`INSERT INTO strava_segments (segment_id, name, activity_type, distance_m, average_grade_pct, maximum_grade_pct, climb_category, elevation_high_m, elevation_low_m, total_elevation_gain_m, private, hazardous, starred, raw_object_hash, payload_json)
+    VALUES ($segmentId, $name, $activityType, $distanceM, $averageGrade, $maximumGrade, $climbCategory, $elevationHigh, $elevationLow, $elevationGain, $private, $hazardous, $starred, $rawHash, $payload)
+    ON CONFLICT (segment_id) DO UPDATE SET
+      name = COALESCE(excluded.name, strava_segments.name),
+      activity_type = COALESCE(excluded.activity_type, strava_segments.activity_type),
+      distance_m = COALESCE(excluded.distance_m, strava_segments.distance_m),
+      average_grade_pct = COALESCE(excluded.average_grade_pct, strava_segments.average_grade_pct),
+      maximum_grade_pct = COALESCE(excluded.maximum_grade_pct, strava_segments.maximum_grade_pct),
+      climb_category = COALESCE(excluded.climb_category, strava_segments.climb_category),
+      elevation_high_m = COALESCE(excluded.elevation_high_m, strava_segments.elevation_high_m),
+      elevation_low_m = COALESCE(excluded.elevation_low_m, strava_segments.elevation_low_m),
+      total_elevation_gain_m = COALESCE(excluded.total_elevation_gain_m, strava_segments.total_elevation_gain_m),
+      private = COALESCE(excluded.private, strava_segments.private),
+      hazardous = COALESCE(excluded.hazardous, strava_segments.hazardous),
+      starred = COALESCE(excluded.starred, strava_segments.starred),
+      raw_object_hash = CASE WHEN $hasDescriptiveFacts THEN excluded.raw_object_hash ELSE strava_segments.raw_object_hash END,
+      payload_json = CASE WHEN $hasDescriptiveFacts THEN excluded.payload_json ELSE strava_segments.payload_json END,
+      updated_at = now()`, {
+        segmentId, name: text(source.name), activityType: text(source.activity_type), distanceM: number(source.distance), averageGrade: number(source.average_grade), maximumGrade: number(source.maximum_grade), climbCategory: number(source.climb_category), elevationHigh: number(source.elevation_high), elevationLow: number(source.elevation_low), elevationGain: number(source.total_elevation_gain), private: typeof source.private === 'boolean' ? source.private : null, hazardous: typeof source.hazardous === 'boolean' ? source.hazardous : null, starred: typeof source.starred === 'boolean' ? source.starred : null, rawHash, payload: json(source), hasDescriptiveFacts,
+    });
+}
+async function upsertEffort(database, payload, activitySourceId, rawHash, history) {
+    const effortId = text(payload.id);
+    const segment = object(payload.segment);
+    const segmentId = text(segment.id) ?? text(payload.segment_id);
+    if (!effortId || !segmentId)
+        return;
+    await upsertSegment(database, segment, rawHash);
+    const values = {
+        effortId, segmentId, elapsedS: number(payload.elapsed_time), movingS: number(payload.moving_time), distanceM: number(payload.distance), averageWatts: number(payload.average_watts), averageHr: number(payload.average_heartrate), maxHr: number(payload.max_heartrate), averageCadence: number(payload.average_cadence), deviceWatts: typeof payload.device_watts === 'boolean' ? payload.device_watts : null, prRank: number(payload.pr_rank), komRank: number(payload.kom_rank), startedAt: text(payload.start_date), rawHash, payload: json(payload),
+    };
+    if (activitySourceId) {
+        await database.run(`INSERT INTO activity_segments VALUES ($activitySourceId, $effortId, $segmentId, $elapsedS, $movingS, $distanceM, $averageWatts, $averageHr, $maxHr, $averageCadence, $deviceWatts, $prRank, $komRank, $startedAt, $rawHash, $payload)
+      ON CONFLICT (activity_source_id, effort_id) DO UPDATE SET segment_id = excluded.segment_id, elapsed_s = excluded.elapsed_s, moving_s = excluded.moving_s, distance_m = excluded.distance_m, average_watts = excluded.average_watts, average_hr = excluded.average_hr, max_hr = excluded.max_hr, average_cadence = excluded.average_cadence, device_watts = excluded.device_watts, pr_rank = excluded.pr_rank, kom_rank = excluded.kom_rank, started_at = excluded.started_at, raw_object_hash = excluded.raw_object_hash, payload_json = excluded.payload_json`, { activitySourceId, ...values });
+    }
+    if (history) {
+        const activity = object(payload.activity);
+        await database.run(`INSERT INTO strava_segment_efforts (effort_id, segment_id, strava_activity_id, elapsed_s, moving_s, distance_m, average_watts, average_hr, max_hr, average_cadence, device_watts, pr_rank, kom_rank, started_at, raw_object_hash, payload_json)
+      VALUES ($effortId, $segmentId, $activityId, $elapsedS, $movingS, $distanceM, $averageWatts, $averageHr, $maxHr, $averageCadence, $deviceWatts, $prRank, $komRank, $startedAt, $rawHash, $payload)
+      ON CONFLICT (effort_id) DO UPDATE SET segment_id = excluded.segment_id, strava_activity_id = excluded.strava_activity_id, elapsed_s = excluded.elapsed_s, moving_s = excluded.moving_s, distance_m = excluded.distance_m, average_watts = excluded.average_watts, average_hr = excluded.average_hr, max_hr = excluded.max_hr, average_cadence = excluded.average_cadence, device_watts = excluded.device_watts, pr_rank = excluded.pr_rank, kom_rank = excluded.kom_rank, started_at = excluded.started_at, raw_object_hash = excluded.raw_object_hash, payload_json = excluded.payload_json, updated_at = now()`, { activityId: text(activity.id) ?? text(payload.activity_id), ...values });
+    }
+}
+export async function normalizeStravaEntity(database, entity) {
+    const payload = object(entity.payload);
+    await storeGenericEntity(database, entity, payload);
+    if (entity.entityType === 'athlete') {
+        const accountId = text(payload.id) ?? entity.remoteId;
+        await database.insertSourceAccount('strava', accountId, [text(payload.firstname), text(payload.lastname)].filter(Boolean).join(' ') || null, payload);
+        return;
+    }
+    if (entity.entityType === 'segment')
+        return upsertSegment(database, payload, entity.rawObjectHash);
+    if (entity.entityType === 'segment_effort')
+        return upsertEffort(database, payload, null, entity.rawObjectHash, true);
+    if (entity.entityType !== 'activity')
+        return;
+    const activitySourceId = `strava:${entity.remoteId}`;
+    const sport = text(payload.sport_type) ?? text(payload.type);
+    await database.run(`INSERT INTO activities (activity_id, started_at_utc, started_at_local, timezone, sport, name, link_state)
+    VALUES ($activityId, $startedAt, $startedAtLocal, $timezone, $sport, $name, 'unlinked')
+    ON CONFLICT (activity_id) DO UPDATE SET started_at_utc = excluded.started_at_utc, started_at_local = excluded.started_at_local, timezone = excluded.timezone, sport = excluded.sport, name = excluded.name`, { activityId: activitySourceId, startedAt: text(payload.start_date), startedAtLocal: text(payload.start_date_local), timezone: text(payload.timezone), sport, name: text(payload.name) });
+    await database.run(`INSERT INTO activity_sources (activity_source_id, activity_id, provider, remote_activity_id, external_id, raw_object_hash)
+    VALUES ($activitySourceId, $activityId, 'strava', $remoteId, NULL, $rawHash)
+    ON CONFLICT (activity_source_id) DO UPDATE SET activity_id = excluded.activity_id, raw_object_hash = excluded.raw_object_hash`, { activitySourceId, activityId: activitySourceId, remoteId: entity.remoteId, rawHash: entity.rawObjectHash });
+    await database.run(`INSERT INTO activity_summaries VALUES ($activitySourceId, $distanceM, $movingS, $elapsedS, $elevationGain, $calories, $avgHr, $maxHr, $avgPower, NULL, $avgCadence, NULL, NULL, NULL, $metrics)
+    ON CONFLICT (activity_source_id) DO UPDATE SET distance_m = excluded.distance_m, moving_s = excluded.moving_s, elapsed_s = excluded.elapsed_s, elevation_gain_m = excluded.elevation_gain_m, calories = excluded.calories, avg_hr = excluded.avg_hr, max_hr = excluded.max_hr, avg_power = excluded.avg_power, avg_cadence = excluded.avg_cadence, metrics_json = excluded.metrics_json`, { activitySourceId, distanceM: number(payload.distance), movingS: number(payload.moving_time), elapsedS: number(payload.elapsed_time), elevationGain: number(payload.total_elevation_gain), calories: number(payload.calories), avgHr: number(payload.average_heartrate), maxHr: number(payload.max_heartrate), avgPower: number(payload.average_watts), avgCadence: number(payload.average_cadence), metrics: json(payload) });
+    const efforts = Array.isArray(payload.segment_efforts) ? payload.segment_efforts : [];
+    for (const effort of efforts)
+        await upsertEffort(database, object(effort), activitySourceId, entity.rawObjectHash, false);
+    const gearId = text(payload.gear_id);
+    if (gearId)
+        await database.run(`INSERT INTO domain_entities (provider, entity_type, remote_id, parent_remote_id, occurred_on, payload_json, extension_json, raw_object_hash) VALUES ('strava', 'activity_gear', $gearId, $activityId, $occurredOn, $payload, '{}', $rawHash) ON CONFLICT (provider, entity_type, remote_id) DO UPDATE SET parent_remote_id = excluded.parent_remote_id, payload_json = excluded.payload_json, raw_object_hash = excluded.raw_object_hash`, { gearId, activityId: entity.remoteId, occurredOn: dateOnly(payload.start_date), payload: json({ gear_id: gearId, activity_id: entity.remoteId }), rawHash: entity.rawObjectHash });
+}
+//# sourceMappingURL=strava-normalizer.js.map

package/dist/elt/storage/artifacts.d.ts

@@ -0,0 +1,13 @@
+import type { CatencePaths } from '../../contracts/runtime.js';
+import type { Provider } from '../../contracts/staging.js';
+export declare function sha256(contents: string | Uint8Array): string;
+/** Stable object hash used to decide whether expensive activity children changed. */
+export declare function stableJsonHash(value: unknown): string;
+export type StoredArtifact = {
+    contentHash: string;
+    relativePath: string;
+    contentType: string;
+};
+export declare function storeArtifact(paths: CatencePaths, provider: Provider, endpoint: string, remoteId: string | null, contents: string | Uint8Array, extension: string, contentType: string): Promise<StoredArtifact>;
+export declare function storeJsonArtifact(paths: CatencePaths, provider: Provider, endpoint: string, remoteId: string | null, payload: unknown): Promise<StoredArtifact>;
+export declare function appendJsonl(filePath: string, value: unknown): Promise<void>;

package/dist/elt/storage/artifacts.js

@@ -0,0 +1,48 @@
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+function safeSegment(value) {
+    return value.replaceAll(/[^a-zA-Z0-9._-]/g, '_').slice(0, 160) || 'unknown';
+}
+export function sha256(contents) {
+    return createHash('sha256').update(contents).digest('hex');
+}
+/** Stable object hash used to decide whether expensive activity children changed. */
+export function stableJsonHash(value) {
+    return sha256(JSON.stringify(canonicalize(value)));
+}
+function canonicalize(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    if (value && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, child]) => [key, canonicalize(child)]));
+    }
+    return value;
+}
+export async function storeArtifact(paths, provider, endpoint, remoteId, contents, extension, contentType) {
+    const contentHash = sha256(contents);
+    const relativePath = path.join(provider, safeSegment(endpoint), safeSegment(remoteId ?? 'collection'), `${contentHash}.${extension}`);
+    const destination = path.join(paths.raw, relativePath);
+    await mkdir(path.dirname(destination), { recursive: true });
+    try {
+        await readFile(destination);
+    }
+    catch {
+        const temporary = `${destination}.${process.pid}.tmp`;
+        await writeFile(temporary, contents);
+        await rename(temporary, destination);
+    }
+    return { contentHash, relativePath: path.join('raw', relativePath), contentType };
+}
+export async function storeJsonArtifact(paths, provider, endpoint, remoteId, payload) {
+    const contents = `${JSON.stringify(payload, null, 2)}\n`;
+    return storeArtifact(paths, provider, endpoint, remoteId, contents, 'json', 'application/json');
+}
+export async function appendJsonl(filePath, value) {
+    await mkdir(path.dirname(filePath), { recursive: true });
+    const existing = await readFile(filePath, 'utf8').catch(() => '');
+    await writeFile(filePath, `${existing}${JSON.stringify(value)}\n`);
+}
+//# sourceMappingURL=artifacts.js.map

package/dist/elt/storage/database.d.ts

@@ -0,0 +1,74 @@
+import { ReadOnlyRepository } from '../../core/query/repository.js';
+import type { CatencePaths } from '../../contracts/runtime.js';
+import type { QueryBindings, WriteDataStore } from '../../contracts/storage.js';
+import type { Provider } from '../../contracts/staging.js';
+export declare class CatenceDatabase implements WriteDataStore {
+    private readonly instance;
+    private readonly connection;
+    private closed;
+    private constructor();
+    static open(paths: CatencePaths): Promise<CatenceDatabase>;
+    close(): Promise<void>;
+    migrate(): Promise<void>;
+    run(sql: string, values?: QueryBindings): Promise<void>;
+    rows<T extends Record<string, unknown>>(sql: string, values?: QueryBindings): Promise<T[]>;
+    tableNames(query: string): Promise<string[]>;
+    interrupt(): void;
+    beginRun(provider: Provider, fromDate: string, runId?: `${string}-${string}-${string}-${string}-${string}`): Promise<string>;
+    finishRun(runId: string): Promise<void>;
+    addError(runId: string, provider: Provider, endpoint: string, remoteId: string | null, message: string, retryable: boolean): Promise<void>;
+    status(): Promise<Record<string, unknown>>;
+    getRun(runId: string): Promise<{
+        provider: Provider;
+        from_date: string;
+    } | null>;
+    insertSourceAccount(provider: Provider, remoteAccountId: string, displayName: string | null, payload: unknown): Promise<void>;
+    resolveIncrementalWindow(provider: Provider, cursorName: 'daily' | 'activities', toDate: string, initialFromDate: string, lookbackDays: number): Promise<{
+        fromDate: string;
+        toDate: string;
+        source: 'cursor' | 'bootstrap' | 'initial';
+    }>;
+    /**
+     * Return the uncovered historical portion of an explicit backfill range.
+     *
+     * A backfill is normally used to extend history backwards from data already
+     * present locally.  Its newest normalized source date is therefore a
+     * coverage boundary: re-reading that day and everything after it only
+     * creates provider traffic and upserts that the caller did not request.
+     * Callers can opt into the complete explicit range with `includeExisting`.
+     */
+    resolveBackfillWindow(provider: Provider, cursorName: 'daily' | 'activities', fromDate: string, toDate: string, includeExisting?: boolean): Promise<{
+        fromDate: string;
+        toDate: string;
+    } | null>;
+    advanceIncrementalCursor(provider: Provider, cursorName: 'daily' | 'activities', runId: string, coveredThroughDate: string, lookbackDays: number): Promise<void>;
+    activityNeedsDetailSync(provider: Provider, remoteActivityId: string, summaryHash: string): Promise<boolean>;
+    recordActivitySyncState(provider: Provider, remoteActivityId: string, summaryHash: string, runId: string, detailsFetched: boolean): Promise<void>;
+    knownActivitySummaryHashes(provider: Provider): Promise<Record<string, string>>;
+    private latestSourceDate;
+    private upsertCursor;
+}
+/**
+ * A deliberately small read-only facade for the MCP/query process.  It never
+ * applies migrations or exposes a mutating method, so an MCP process cannot
+ * turn a question into a DuckDB write.
+ */
+export declare class ReadOnlyCatenceDatabase {
+    private readonly instance;
+    private readonly connection;
+    private closed;
+    private queryTail;
+    private constructor();
+    static open(paths: CatencePaths): Promise<ReadOnlyCatenceDatabase>;
+    close(): Promise<void>;
+    rows<T extends Record<string, unknown>>(sql: string, values?: QueryBindings): Promise<T[]>;
+    tableNames(query: string): Promise<string[]>;
+    interrupt(): void;
+    private withConnection;
+}
+/** Compose core read services with the DuckDB-backed, read-only adapter. */
+export declare function openReadOnlyRepository(paths: CatencePaths): Promise<ReadOnlyRepository>;
+export declare class ReadOnlyDatabaseError extends Error {
+    readonly code: 'data_sync_in_progress' | 'data_unavailable';
+    constructor(code: 'data_sync_in_progress' | 'data_unavailable', message: string);
+}

package/dist/elt/storage/database.js

@@ -0,0 +1,296 @@
+import { DuckDBInstance } from '@duckdb/node-api';
+import { randomUUID } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { ReadOnlyRepository } from '../../core/query/repository.js';
+import { migrations } from './migrations.js';
+import { json } from './sql.js';
+export class CatenceDatabase {
+    instance;
+    connection;
+    closed = false;
+    constructor(instance, connection) {
+        this.instance = instance;
+        this.connection = connection;
+    }
+    static async open(paths) {
+        const instance = await DuckDBInstance.create(paths.database);
+        const connection = await instance.connect();
+        const database = new CatenceDatabase(instance, connection);
+        await database.migrate();
+        return database;
+    }
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        try {
+            // A connection must be disconnected before its owning instance. Keeping
+            // the instance alive for the full database lifetime also prevents the
+            // native binding from releasing it during an in-flight connection close.
+            this.connection.closeSync();
+        }
+        finally {
+            this.instance.closeSync();
+        }
+    }
+    async migrate() {
+        await this.connection.run('CREATE TABLE IF NOT EXISTS schema_migrations (version INTEGER PRIMARY KEY, name VARCHAR NOT NULL, applied_at TIMESTAMPTZ NOT NULL DEFAULT now())');
+        const rows = await this.rows('SELECT version FROM schema_migrations');
+        const applied = new Set(rows.map((row) => Number(row.version)));
+        for (const migration of migrations) {
+            if (applied.has(migration.version))
+                continue;
+            await this.connection.run('BEGIN TRANSACTION');
+            try {
+                await this.connection.run(migration.sql);
+                await this.connection.run('INSERT INTO schema_migrations (version, name) VALUES ($version, $name)', { version: migration.version, name: migration.name });
+                await this.connection.run('COMMIT');
+            }
+            catch (error) {
+                await this.connection.run('ROLLBACK');
+                throw error;
+            }
+        }
+        // Some DuckDB builds abort while committing an index rebuild in the same
+        // transaction as an ALTER on its populated table. These statements are
+        // idempotent and retried on every open, so a process interruption after a
+        // migration commit cannot leave the database permanently under-indexed.
+        for (const migration of migrations) {
+            if (migration.postCommitSql)
+                await this.connection.run(migration.postCommitSql);
+        }
+    }
+    async run(sql, values) {
+        await this.connection.run(sql, values);
+    }
+    async rows(sql, values) {
+        const result = await this.connection.runAndReadAll(sql, values);
+        return result.getRowObjectsJS();
+    }
+    async tableNames(query) {
+        return [...this.connection.getTableNames(query, true)];
+    }
+    interrupt() {
+        this.connection.interrupt();
+    }
+    async beginRun(provider, fromDate, runId = randomUUID()) {
+        await this.run('INSERT INTO sync_runs (run_id, provider, from_date, started_at, status, parser_version) VALUES ($runId, $provider, $fromDate, now(), \'running\', 1)', { runId, provider, fromDate });
+        return runId;
+    }
+    async finishRun(runId) {
+        await this.run(`UPDATE sync_runs SET status = CASE WHEN error_count > 0 THEN 'completed_with_errors' ELSE 'completed' END, completed_at = now() WHERE run_id = $runId`, { runId });
+        await this.run("UPDATE retrieval_index_state SET status = 'stale' WHERE index_name = 'context'");
+    }
+    async addError(runId, provider, endpoint, remoteId, message, retryable) {
+        await this.run(`INSERT INTO normalization_errors (error_id, run_id, provider, endpoint, remote_id, message, retryable)
+       VALUES ($errorId, $runId, $provider, $endpoint, $remoteId, $message, $retryable)`, { errorId: randomUUID(), runId, provider, endpoint, remoteId, message, retryable });
+        await this.run('UPDATE sync_runs SET error_count = error_count + 1 WHERE run_id = $runId', { runId });
+    }
+    async status() {
+        // @duckdb/node-api owns native statement state on the connection. Keep
+        // status reads sequential instead of issuing several native calls at once.
+        const runs = await this.rows('SELECT status, count(*)::INTEGER AS count FROM sync_runs GROUP BY status');
+        const errors = await this.rows('SELECT count(*)::INTEGER AS count FROM normalization_errors WHERE resolved_at IS NULL');
+        const rawObjects = await this.rows('SELECT count(*)::INTEGER AS count FROM raw_objects');
+        const activities = await this.rows('SELECT count(*)::INTEGER AS count FROM activities');
+        const streams = await this.rows('SELECT count(*)::INTEGER AS count FROM stream_manifest');
+        const cursors = await this.rows('SELECT provider, cursor_name, cast(covered_through_date AS VARCHAR) AS covered_through_date, cast(latest_source_date AS VARCHAR) AS latest_source_date, lookback_days, last_successful_run_id, cast(last_completed_at AS VARCHAR) AS last_completed_at, status FROM sync_cursors ORDER BY provider, cursor_name');
+        return {
+            runs, unresolvedErrors: errors[0]?.count ?? 0, rawObjects: rawObjects[0]?.count ?? 0, activities: activities[0]?.count ?? 0, streams: streams[0]?.count ?? 0,
+            cursors: cursors.map((cursor) => ({ ...cursor, next_from_date: subtractDays(cursor.covered_through_date, Number(cursor.lookback_days)) })),
+        };
+    }
+    async getRun(runId) {
+        const rows = await this.rows('SELECT provider, cast(from_date AS VARCHAR) AS from_date FROM sync_runs WHERE run_id = $runId', { runId });
+        return rows[0] ?? null;
+    }
+    async insertSourceAccount(provider, remoteAccountId, displayName, payload) {
+        await this.run(`INSERT OR REPLACE INTO source_accounts VALUES ($provider, $remoteAccountId, $displayName, now(), $payload)`, { provider, remoteAccountId, displayName, payload: json(payload) });
+    }
+    async resolveIncrementalWindow(provider, cursorName, toDate, initialFromDate, lookbackDays) {
+        const cursor = await this.rows(`SELECT cast(covered_through_date AS VARCHAR) AS covered_through_date
+       FROM sync_cursors WHERE provider = $provider AND cursor_name = $cursorName`, { provider, cursorName });
+        if (cursor[0]?.covered_through_date) {
+            return { fromDate: subtractDays(cursor[0].covered_through_date, lookbackDays), toDate, source: 'cursor' };
+        }
+        const latestSourceDate = await this.latestSourceDate(provider, cursorName);
+        if (latestSourceDate) {
+            await this.upsertCursor(provider, cursorName, toDate, latestSourceDate, lookbackDays, null, 'bootstrap', { initializedFrom: 'normalized_source_dates' });
+            return { fromDate: subtractDays(latestSourceDate, lookbackDays), toDate, source: 'bootstrap' };
+        }
+        return { fromDate: initialFromDate, toDate, source: 'initial' };
+    }
+    /**
+     * Return the uncovered historical portion of an explicit backfill range.
+     *
+     * A backfill is normally used to extend history backwards from data already
+     * present locally.  Its newest normalized source date is therefore a
+     * coverage boundary: re-reading that day and everything after it only
+     * creates provider traffic and upserts that the caller did not request.
+     * Callers can opt into the complete explicit range with `includeExisting`.
+     */
+    async resolveBackfillWindow(provider, cursorName, fromDate, toDate, includeExisting = false) {
+        if (includeExisting)
+            return { fromDate, toDate };
+        const latestSourceDate = await this.latestSourceDate(provider, cursorName);
+        if (!latestSourceDate || latestSourceDate < fromDate)
+            return { fromDate, toDate };
+        if (latestSourceDate >= toDate)
+            return null;
+        const uncoveredThrough = subtractDays(latestSourceDate, 1);
+        return uncoveredThrough < fromDate ? null : { fromDate, toDate: uncoveredThrough };
+    }
+    async advanceIncrementalCursor(provider, cursorName, runId, coveredThroughDate, lookbackDays) {
+        const latestSourceDate = await this.latestSourceDate(provider, cursorName);
+        const run = await this.rows('SELECT error_count FROM sync_runs WHERE run_id = $runId', { runId });
+        const status = Number(run[0]?.error_count ?? 0) > 0 ? 'completed_with_errors' : 'completed';
+        await this.upsertCursor(provider, cursorName, coveredThroughDate, latestSourceDate, lookbackDays, runId, status, { reconciliation: 'overlap_window' });
+    }
+    async activityNeedsDetailSync(provider, remoteActivityId, summaryHash) {
+        const rows = await this.rows('SELECT summary_hash FROM activity_sync_state WHERE provider = $provider AND remote_activity_id = $remoteActivityId', { provider, remoteActivityId });
+        return rows[0]?.summary_hash !== summaryHash;
+    }
+    async recordActivitySyncState(provider, remoteActivityId, summaryHash, runId, detailsFetched) {
+        await this.run(`INSERT INTO activity_sync_state (provider, remote_activity_id, summary_hash, last_seen_run_id, last_detail_sync_at, details_status)
+       VALUES ($provider, $remoteActivityId, $summaryHash, $runId, CASE WHEN $detailsFetched THEN now() ELSE NULL END, CASE WHEN $detailsFetched THEN 'attempted' ELSE 'unchanged' END)
+       ON CONFLICT (provider, remote_activity_id) DO UPDATE SET
+         summary_hash = excluded.summary_hash,
+         last_seen_run_id = excluded.last_seen_run_id,
+         last_seen_at = now(),
+         last_detail_sync_at = CASE WHEN $detailsFetched THEN now() ELSE activity_sync_state.last_detail_sync_at END,
+         details_status = CASE WHEN $detailsFetched THEN 'attempted' ELSE activity_sync_state.details_status END`, { provider, remoteActivityId, summaryHash, runId, detailsFetched });
+    }
+    async knownActivitySummaryHashes(provider) {
+        const rows = await this.rows('SELECT remote_activity_id, summary_hash FROM activity_sync_state WHERE provider = $provider', { provider });
+        return Object.fromEntries(rows.map((row) => [row.remote_activity_id, row.summary_hash]));
+    }
+    async latestSourceDate(provider, cursorName) {
+        const observations = cursorName === 'daily'
+            ? `SELECT max(metric_date) AS observed_date FROM daily_metrics WHERE provider = $provider
+         UNION ALL SELECT max(nutrition_date) FROM nutrition_days WHERE provider = $provider
+         UNION ALL SELECT max(occurred_on) FROM source_entities WHERE provider = $provider AND entity_type IN ('wellness', 'daily_health', 'nutrition_day', 'nutrition_log')`
+            : `SELECT max(cast(started_at_utc AS DATE)) AS observed_date FROM activities activity
+           JOIN activity_sources source USING (activity_id) WHERE source.provider = $provider
+         UNION ALL SELECT max(occurred_on) FROM source_entities WHERE provider = $provider AND entity_type = 'activity'`;
+        const rows = await this.rows(`
+      SELECT max(observed_date) AS latest_source_date FROM (${observations})
+    `, { provider });
+        return toIsoDate(rows[0]?.latest_source_date ?? null);
+    }
+    async upsertCursor(provider, cursorName, coveredThroughDate, latestSourceDate, lookbackDays, runId, status, detail) {
+        await this.run(`INSERT INTO sync_cursors (provider, cursor_name, covered_through_date, latest_source_date, lookback_days, last_successful_run_id, last_completed_at, status, detail_json)
+       VALUES ($provider, $cursorName, $coveredThroughDate, $latestSourceDate, $lookbackDays, $runId, now(), $status, $detail)
+       ON CONFLICT (provider, cursor_name) DO UPDATE SET
+         covered_through_date = excluded.covered_through_date,
+         latest_source_date = excluded.latest_source_date,
+         lookback_days = excluded.lookback_days,
+         last_successful_run_id = excluded.last_successful_run_id,
+         last_completed_at = excluded.last_completed_at,
+         status = excluded.status,
+         detail_json = excluded.detail_json`, { provider, cursorName, coveredThroughDate, latestSourceDate, lookbackDays, runId, status, detail: json(detail) });
+    }
+}
+function toIsoDate(value) {
+    if (value instanceof Date)
+        return value.toISOString().slice(0, 10);
+    if (typeof value === 'string' && /^\d{4}-\d{2}-\d{2}/.test(value))
+        return value.slice(0, 10);
+    return null;
+}
+function subtractDays(date, days) {
+    const timestamp = Date.parse(`${date}T00:00:00Z`);
+    return new Date(timestamp - days * 86_400_000).toISOString().slice(0, 10);
+}
+/**
+ * A deliberately small read-only facade for the MCP/query process.  It never
+ * applies migrations or exposes a mutating method, so an MCP process cannot
+ * turn a question into a DuckDB write.
+ */
+export class ReadOnlyCatenceDatabase {
+    instance;
+    connection;
+    closed = false;
+    // @duckdb/node-api shares prepared-statement state on a connection. Query
+    // services may compose independent reads with Promise.all(), so serialize at
+    // this boundary instead of relying on every caller to remember that detail.
+    queryTail = Promise.resolve();
+    constructor(instance, connection) {
+        this.instance = instance;
+        this.connection = connection;
+    }
+    static async open(paths) {
+        if (!existsSync(paths.database)) {
+            throw new ReadOnlyDatabaseError('data_unavailable', 'No Catence database exists yet. Complete a sync before starting MCP.');
+        }
+        try {
+            const instance = await DuckDBInstance.create(paths.database, { access_mode: 'READ_ONLY' });
+            const connection = await instance.connect();
+            const database = new ReadOnlyCatenceDatabase(instance, connection);
+            const migration = await database.rows('SELECT max(version) AS version FROM schema_migrations');
+            const currentVersion = Number(migration[0]?.version ?? 0);
+            const requiredVersion = Math.max(...migrations.map((item) => item.version));
+            if (currentVersion < requiredVersion) {
+                await database.close();
+                throw new ReadOnlyDatabaseError('data_unavailable', `Database schema is at version ${currentVersion}; version ${requiredVersion} is required. Run a sync or build-retrieval-index once.`);
+            }
+            return database;
+        }
+        catch (error) {
+            if (error instanceof ReadOnlyDatabaseError)
+                throw error;
+            const message = error instanceof Error ? error.message : String(error);
+            const code = /lock|busy|conflict|read.?only|another process/i.test(message) ? 'data_sync_in_progress' : 'data_unavailable';
+            throw new ReadOnlyDatabaseError(code, `Read-only data snapshot is unavailable: ${message}`);
+        }
+    }
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        await this.queryTail;
+        try {
+            this.connection.closeSync();
+        }
+        finally {
+            this.instance.closeSync();
+        }
+    }
+    async rows(sql, values) {
+        return this.withConnection(async () => {
+            const result = await this.connection.runAndReadAll(sql, values);
+            return result.getRowObjectsJS();
+        });
+    }
+    async tableNames(query) {
+        return this.withConnection(async () => [...this.connection.getTableNames(query, true)]);
+    }
+    interrupt() {
+        this.connection.interrupt();
+    }
+    async withConnection(operation) {
+        let release;
+        const completed = new Promise((resolve) => { release = resolve; });
+        const previous = this.queryTail;
+        this.queryTail = completed;
+        await previous;
+        try {
+            return await operation();
+        }
+        finally {
+            release?.();
+        }
+    }
+}
+/** Compose core read services with the DuckDB-backed, read-only adapter. */
+export async function openReadOnlyRepository(paths) {
+    return new ReadOnlyRepository(await ReadOnlyCatenceDatabase.open(paths), paths);
+}
+export class ReadOnlyDatabaseError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'ReadOnlyDatabaseError';
+    }
+}
+//# sourceMappingURL=database.js.map

package/dist/elt/storage/migrations.d.ts

@@ -0,0 +1,3 @@
+import { type Migration } from './migrations.legacy.js';
+export declare const migrations: Migration[];
+export type { Migration };