catence 0.0.0 → 0.2.0-beta.1

package/README.md

@@ -1,45 +1,217 @@
-# catence
+# Catence
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+Catence is a local-first fitness MCP server for Garmin, Intervals.icu, and targeted Strava enrichment. It gives an agent evidence-backed access to normalized training, wellness, activity, stream, segment, and gear data without uploading the underlying dataset to Catence.
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
+![Catence](docs/assets/image.png)
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+## What is included
 
-## Purpose
+- Garmin, Intervals.icu, and Strava ingestion with source-aware normalization.
+- Read-only MCP tools, plus explicitly named, lock-guarded Strava hydration tools.
+- One shared Catence agent can serve several isolated athlete stores. Every personal-data MCP call names an `athleteId`; Catence never silently combines athletes.
+- A password-protected Chainlit Console with an authenticated dashboard.
+- A generated demo catalog for safe evaluation in Glama, desktop MCP clients, or local development.
 
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `catence`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
+Catence helps explore recovery, training load, trends, activity detail, swimming/cycling/running progress, segments, gear, and data quality. It reports the evidence and coverage it can see; it does not diagnose or prescribe training.
 
-## What is OIDC Trusted Publishing?
+## Requirements
 
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
+- Node.js 22+
+- Python 3.12+ and [uv](https://docs.astral.sh/uv/) for Garmin and Strava provider workers
+- Provider credentials for the athletes you choose to sync
 
-## Setup Instructions
+## Quick start
 
-To properly configure OIDC trusted publishing for this package:
+Install Catence and create the first athlete. The default catalog home is `~/.catence`; set `CATENCE_HOME` or pass `--home` to use a different location.
 
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
+```sh
+npm install --global catence@0.2.0
+catence-data setup --athlete alex --label "Alex"
+```
 
-## DO NOT USE THIS PACKAGE
+Store each provider value through stdin so it does not enter shell history. Values are written to the selected athlete’s owner-only local secret file.
 
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
+```sh
+printf %s 'alex@example.com' | catence-data --athlete alex secret set --provider garmin --field email --value-stdin
+printf %s 'your-garmin-password' | catence-data --athlete alex secret set --provider garmin --field password --value-stdin
+printf %s 'intervals-api-key' | catence-data --athlete alex secret set --provider intervals --field apiKey --value-stdin
+printf %s '12345' | catence-data --athlete alex secret set --provider intervals --field athleteId --value-stdin
+```
 
-## More Information
+Sync and create retrieval context:
 
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
+```sh
+catence-data --athlete alex sync --provider all
+catence-data --athlete alex build-retrieval-index
+```
 
----
+Start the stdio MCP server:
 
-**Maintained for OIDC setup purposes only**
+```sh
+catence
+```
+
+An agent first calls `list_athletes`, then includes `athleteId` with every data tool. This is intentional: a shared agent may access the stores you configured, but no tool implicitly aggregates or crosses between athletes.
+
+### Add another athlete
+
+```sh
+catence-data athlete add --id sam --label "Sam"
+printf %s 'sam@example.com' | catence-data --athlete sam secret set --provider garmin --field email --value-stdin
+printf %s 'sam-password' | catence-data --athlete sam secret set --provider garmin --field password --value-stdin
+catence-data --athlete sam sync --provider garmin
+catence-data athlete list
+```
+
+The catalog layout is deliberately simple:
+
+```text
+~/.catence/
+  catalog.json
+  config.json                     # shared Console configuration; no secrets
+  console/chat-history.sqlite3
+  athletes/
+    alex/                         # isolated DuckDB, raw data, and tokens
+      secrets/providers.json      # mode 0600
+    sam/
+      ...
+```
+
+Garmin, Intervals, and Strava client credentials are isolated per athlete. Strava OAuth tokens remain in that athlete’s own store. The old 0.1 single-store directory cannot be migrated safely: create a fresh home and re-sync each athlete.
+
+### Common operations
+
+```sh
+# Incremental or explicit data work for one athlete
+catence-data --athlete alex status
+catence-data --athlete alex sync --provider intervals
+catence-data --athlete alex sync --provider garmin --from 2025-07-29
+catence-data --athlete alex backfill --provider garmin --from 2020-01-01 --refresh
+catence-data --athlete alex retry --run <run-id>
+
+# Strava OAuth uses clientId and clientSecret previously stored for this athlete
+catence-data --athlete alex auth strava --callback
+catence-data --athlete alex disconnect strava
+
+# Choose a non-default catalog location
+catence-data --home /srv/catence setup --athlete alex --label "Alex"
+catence --home /srv/catence
+```
+
+Register `http://127.0.0.1:8765/strava/callback` with the Strava application for the callback flow. The manual `auth strava --code <authorization-code>` flow remains available for headless environments.
+
+## Safe demo and Glama
+
+Run a clearly marked generated dataset without provider accounts:
+
+```sh
+npx --yes catence@0.2.0 demo
+```
+
+It creates or reuses `~/.catence-demo` with one `demo` athlete. The generated data has explicit caveats in every tool response and never contains personal measurements. The Glama registry entry uses this command for **Try in Browser**, so the hosted sandbox has no access to local credentials or personal data.
+
+From a checkout:
+
+```sh
+npm run mcp -- demo
+```
+
+## MCP clients and HTTP
+
+For a packaged installation, point a client at `catence`:
+
+```sh
+codex mcp add catence -- catence
+claude mcp add --transport stdio catence -- catence
+```
+
+For a source checkout:
+
+```sh
+codex mcp add catence -- npm --prefix /absolute/path/to/catence run mcp
+```
+
+Optional local Streamable HTTP MCP and dashboard APIs:
+
+```sh
+catence serve --host 127.0.0.1 --port 8787
+```
+
+`GET /api/v1/athletes` returns IDs and labels only. `GET /api/v1/dashboard` requires `athleteId`, for example `http://127.0.0.1:8787/api/v1/dashboard?athleteId=alex&days=28`. Browser origins must be listed with `--allow-origin`; the packaged Console instead proxies the dashboard through its authenticated same-origin route.
+
+## Catence Console
+
+The Console is a local web chat that starts a matching Catence HTTP server on loopback. It uses Chainlit password login and fails closed unless all three authentication variables are supplied.
+
+```sh
+export CATENCE_HOME="$HOME/.catence"
+export CATENCE_CONSOLE_USERNAME='coach'
+export CATENCE_CONSOLE_PASSWORD_HASH="$(catence-console auth hash-password)"
+export CHAINLIT_AUTH_SECRET="$(openssl rand -hex 32)"
+export OPENAI_API_KEY='…'
+
+uvx catence-console@0.2.0 serve
+```
+
+On the first authenticated visit, the Console wizard asks for an Azure, OpenAI, or Anthropic model and writes only the non-secret model configuration to `~/.catence/config.json`. Model-provider keys remain process environment variables. The Console settings include an athlete selector; the server overwrites model-supplied athlete scope with that selected value on every personal-data call.
+
+To preflight the Console and a running runtime:
+
+```sh
+uvx catence-console@0.2.0 doctor --home "$HOME/.catence" --mcp-url http://127.0.0.1:8787/mcp
+```
+
+Console chats and saved tool context are local at `~/.catence/console/chat-history.sqlite3`.
+
+### Docker and Cloudflare Tunnel
+
+The Console image contains the Node runtime, Catence, and Console. Its MCP server remains loopback-only inside the container; only the Console port is exposed.
+
+```sh
+docker build -f console/Dockerfile -t catence-console .
+docker run --rm -p 127.0.0.1:8000:8000 -v catence-data:/data \
+  -e CATENCE_CONSOLE_USERNAME='coach' \
+  -e CATENCE_CONSOLE_PASSWORD_HASH='replace-with-bcrypt-hash' \
+  -e CHAINLIT_AUTH_SECRET='replace-with-a-long-random-secret' \
+  -e OPENAI_API_KEY='…' \
+  catence-console
+```
+
+Initialize the mounted volume before its first production sync, for example:
+
+```sh
+docker run --rm -it -v catence-data:/data --entrypoint catence-data catence-console \
+  setup --athlete alex --label "Alex"
+```
+
+Use the same `--entrypoint catence-data` pattern for `secret set` and `sync`. Route a Cloudflare Tunnel to `http://127.0.0.1:8000`; do not run a tunnel client in this image. Use HTTPS at the tunnel and retain the Console login—the dashboard is fetched through the authenticated Console origin rather than directly from port 8787.
+
+## Configuration
+
+[`config.example.json`](config.example.json) documents rate limits, Strava budgets, and Console model profiles. It intentionally contains environment-variable names rather than credential values. Keep per-athlete provider values in `catence-data secret set`, not in `.env` or `config.json`.
+
+For source development:
+
+```sh
+npm ci
+npm run check
+npm test
+UV_CACHE_DIR=$PWD/.cache/uv uv run --project console --group dev python -m pytest console/tests -q
+```
+
+## Beta releases
+
+Registry betas use distinct npm and Python prerelease formats: for example,
+`catence@0.2.0-beta.1` pairs with `catence-console==0.2.0b1` and
+`catence-chainlit==0.2.0b1`. The protected `beta` branch verifies candidates;
+a `v0.2.0-beta.1` tag publishes to npm's `beta` channel and creates a GitHub
+prerelease. Follow [the beta release checklist](release/beta-checklist.md) to
+publish the UI wheel first, deploy the registry artifacts with Compose, and
+test the MCP and authenticated Console on a server without touching production
+data.
+
+## Data and caveats
+
+Garmin is the primary source for activity and wellness data; Intervals.icu supplements training analysis; Strava is used for targeted segments, efforts, and gear. Missing fields mean a provider did not supply a value. The source credentials and source APIs determine the data available. Catence does not use the official Garmin API; Garmin sync relies on the selected athlete’s email/password credentials.
+
+See [distribution notes](docs/distribution.md) for release artifacts, including APM and MCPB demo bundles.

package/config.example.json

@@ -0,0 +1,63 @@
+{
+  "mcp": {
+    "rateLimits": {
+      "server": { "requests": 240, "windowSeconds": 60 },
+      "tools": {
+        "*": { "requests": 60, "windowSeconds": 60 },
+        "hydrate_strava_activity": { "requests": 6, "windowSeconds": 60 },
+        "hydrate_recent_strava_activities": { "requests": 1, "windowSeconds": 60 },
+        "hydrate_strava_segment_history": { "requests": 4, "windowSeconds": 60 }
+      },
+      "resources": {
+        "*": { "requests": 120, "windowSeconds": 60 }
+      }
+    }
+  },
+  "providers": {
+    "strava": {
+      "budget": {
+        "maxConcurrentRequests": 1,
+        "readRequestsPer15Minutes": 80,
+        "readRequestsPerDay": 800
+      }
+    }
+  },
+  "console": {
+    "defaultProfile": "azure-foundry",
+    "limits": {
+      "toolRounds": 8,
+      "toolResultCharacters": 24000
+    },
+    "profiles": {
+      "azure-foundry": {
+        "label": "Azure Foundry",
+        "defaultModel": "terra",
+        "defaultReasoningEffort": "medium",
+        "models": {
+          "terra": { "label": "GPT-5.6 Terra", "model": "azure_ai/gpt-5.6-terra" },
+          "luna": { "label": "GPT-5.6 Luna", "model": "azure_ai/gpt-5.6-luna" },
+          "sol": { "label": "GPT-5.6 Sol", "model": "azure_ai/gpt-5.6-sol" }
+        },
+        "apiKeyEnv": "AZURE_API_KEY",
+        "apiBaseEnv": "AZURE_API_BASE",
+        "apiVersionEnv": "AZURE_API_VERSION"
+      },
+      "opencode": {
+        "label": "OpenCode-compatible",
+        "model": "openai/your-model-name",
+        "apiKeyEnv": "OPENCODE_API_KEY",
+        "apiBaseEnv": "OPENCODE_API_BASE"
+      },
+      "openai": {
+        "label": "OpenAI",
+        "model": "openai/gpt-5-mini",
+        "apiKeyEnv": "OPENAI_API_KEY"
+      },
+      "anthropic": {
+        "label": "Anthropic",
+        "model": "anthropic/claude-sonnet-4-5",
+        "apiKeyEnv": "ANTHROPIC_API_KEY"
+      }
+    }
+  }
+}

package/dist/contracts/index.d.ts

@@ -0,0 +1,4 @@
+export * from './runtime.js';
+export * from './release.js';
+export * from './staging.js';
+export * from './storage.js';

package/dist/contracts/index.js

@@ -0,0 +1,5 @@
+export * from './runtime.js';
+export * from './release.js';
+export * from './staging.js';
+export * from './storage.js';
+//# sourceMappingURL=index.js.map

package/dist/contracts/release.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Stable runtime contract used by independently distributed Catence clients.
+ * Keep these values synchronized with release/manifest.json; release checks
+ * deliberately reject drift before a package can be published.
+ */
+export declare const CATENCE_RUNTIME_VERSION = "0.2.0-beta.1";
+export declare const CATENCE_PROTOCOL_VERSION = 1;
+export type CatenceRuntimeCapabilities = {
+    mcp: true;
+    dashboardApi: 1;
+    demoStore: true;
+};
+export type CatenceRuntimeHealth = {
+    status: 'ok';
+    service: 'catence';
+    runtimeVersion: string;
+    protocolVersion: number;
+    capabilities: CatenceRuntimeCapabilities;
+};
+export declare function catenceRuntimeHealth(): CatenceRuntimeHealth;

package/dist/contracts/release.js

@@ -0,0 +1,17 @@
+/**
+ * Stable runtime contract used by independently distributed Catence clients.
+ * Keep these values synchronized with release/manifest.json; release checks
+ * deliberately reject drift before a package can be published.
+ */
+export const CATENCE_RUNTIME_VERSION = '0.2.0-beta.1';
+export const CATENCE_PROTOCOL_VERSION = 1;
+export function catenceRuntimeHealth() {
+    return {
+        status: 'ok',
+        service: 'catence',
+        runtimeVersion: CATENCE_RUNTIME_VERSION,
+        protocolVersion: CATENCE_PROTOCOL_VERSION,
+        capabilities: { mcp: true, dashboardApi: 1, demoStore: true },
+    };
+}
+//# sourceMappingURL=release.js.map

package/dist/contracts/runtime.d.ts

@@ -0,0 +1,11 @@
+/** Paths owned by one isolated local Catence data store. */
+export type CatencePaths = {
+    root: string;
+    database: string;
+    raw: string;
+    lake: string;
+    staging: string;
+    config: string;
+    secrets: string;
+    lock: string;
+};

package/dist/contracts/runtime.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=runtime.js.map

package/dist/contracts/staging.d.ts

@@ -0,0 +1,183 @@
+import { z } from 'zod';
+export declare const PROVIDERS: readonly ["intervals", "garmin", "strava"];
+export type Provider = (typeof PROVIDERS)[number];
+export declare const STAGING_SCHEMA_VERSION = 1;
+export declare const rawObjectSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"raw_object">;
+    schemaVersion: z.ZodLiteral<1>;
+    provider: z.ZodEnum<{
+        intervals: "intervals";
+        garmin: "garmin";
+        strava: "strava";
+    }>;
+    endpoint: z.ZodString;
+    remoteId: z.ZodNullable<z.ZodString>;
+    fetchedAt: z.ZodString;
+    contentHash: z.ZodString;
+    contentType: z.ZodString;
+    relativePath: z.ZodString;
+    scope: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export declare const runManifestSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"run_manifest">;
+    schemaVersion: z.ZodLiteral<1>;
+    provider: z.ZodEnum<{
+        intervals: "intervals";
+        garmin: "garmin";
+        strava: "strava";
+    }>;
+    runId: z.ZodString;
+    fromDate: z.ZodString;
+    createdAt: z.ZodString;
+}, z.core.$strip>;
+export declare const sourceEntitySchema: z.ZodObject<{
+    kind: z.ZodLiteral<"source_entity">;
+    schemaVersion: z.ZodLiteral<1>;
+    provider: z.ZodEnum<{
+        intervals: "intervals";
+        garmin: "garmin";
+        strava: "strava";
+    }>;
+    entityType: z.ZodString;
+    remoteId: z.ZodString;
+    parentRemoteId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    occurredOn: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    sourceUpdatedAt: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    rawObjectHash: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    payload: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    extension: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export declare const streamManifestSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"stream_manifest">;
+    schemaVersion: z.ZodLiteral<1>;
+    provider: z.ZodEnum<{
+        intervals: "intervals";
+        garmin: "garmin";
+        strava: "strava";
+    }>;
+    activityRemoteId: z.ZodString;
+    relativePath: z.ZodString;
+    contentHash: z.ZodString;
+    rowCount: z.ZodNumber;
+    startAt: z.ZodNullable<z.ZodString>;
+    endAt: z.ZodNullable<z.ZodString>;
+    columns: z.ZodArray<z.ZodString>;
+    rawObjectHash: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export declare const activitySyncStateSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"activity_sync_state">;
+    schemaVersion: z.ZodLiteral<1>;
+    provider: z.ZodEnum<{
+        intervals: "intervals";
+        garmin: "garmin";
+        strava: "strava";
+    }>;
+    activityRemoteId: z.ZodString;
+    summaryHash: z.ZodString;
+    detailsFetched: z.ZodBoolean;
+}, z.core.$strip>;
+export declare const extractionErrorSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"extraction_error">;
+    schemaVersion: z.ZodLiteral<1>;
+    provider: z.ZodEnum<{
+        intervals: "intervals";
+        garmin: "garmin";
+        strava: "strava";
+    }>;
+    endpoint: z.ZodString;
+    remoteId: z.ZodNullable<z.ZodString>;
+    message: z.ZodString;
+    retryable: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export declare const stagingRecordSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"run_manifest">;
+    schemaVersion: z.ZodLiteral<1>;
+    provider: z.ZodEnum<{
+        intervals: "intervals";
+        garmin: "garmin";
+        strava: "strava";
+    }>;
+    runId: z.ZodString;
+    fromDate: z.ZodString;
+    createdAt: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"raw_object">;
+    schemaVersion: z.ZodLiteral<1>;
+    provider: z.ZodEnum<{
+        intervals: "intervals";
+        garmin: "garmin";
+        strava: "strava";
+    }>;
+    endpoint: z.ZodString;
+    remoteId: z.ZodNullable<z.ZodString>;
+    fetchedAt: z.ZodString;
+    contentHash: z.ZodString;
+    contentType: z.ZodString;
+    relativePath: z.ZodString;
+    scope: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"source_entity">;
+    schemaVersion: z.ZodLiteral<1>;
+    provider: z.ZodEnum<{
+        intervals: "intervals";
+        garmin: "garmin";
+        strava: "strava";
+    }>;
+    entityType: z.ZodString;
+    remoteId: z.ZodString;
+    parentRemoteId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    occurredOn: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    sourceUpdatedAt: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    rawObjectHash: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    payload: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    extension: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"stream_manifest">;
+    schemaVersion: z.ZodLiteral<1>;
+    provider: z.ZodEnum<{
+        intervals: "intervals";
+        garmin: "garmin";
+        strava: "strava";
+    }>;
+    activityRemoteId: z.ZodString;
+    relativePath: z.ZodString;
+    contentHash: z.ZodString;
+    rowCount: z.ZodNumber;
+    startAt: z.ZodNullable<z.ZodString>;
+    endAt: z.ZodNullable<z.ZodString>;
+    columns: z.ZodArray<z.ZodString>;
+    rawObjectHash: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"activity_sync_state">;
+    schemaVersion: z.ZodLiteral<1>;
+    provider: z.ZodEnum<{
+        intervals: "intervals";
+        garmin: "garmin";
+        strava: "strava";
+    }>;
+    activityRemoteId: z.ZodString;
+    summaryHash: z.ZodString;
+    detailsFetched: z.ZodBoolean;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"extraction_error">;
+    schemaVersion: z.ZodLiteral<1>;
+    provider: z.ZodEnum<{
+        intervals: "intervals";
+        garmin: "garmin";
+        strava: "strava";
+    }>;
+    endpoint: z.ZodString;
+    remoteId: z.ZodNullable<z.ZodString>;
+    message: z.ZodString;
+    retryable: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>], "kind">;
+export type StagingRecord = z.infer<typeof stagingRecordSchema>;
+export type SourceEntity = z.infer<typeof sourceEntitySchema>;
+export type EndpointSpec = {
+    readonly provider: Provider;
+    readonly name: string;
+    readonly scope: 'singleton' | 'date_range' | 'activity' | 'collection' | 'child';
+    readonly entityType: string;
+    readonly readOnly: true;
+    readonly pagination: 'none' | 'offset' | 'provider';
+};

package/dist/contracts/staging.js

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+export const PROVIDERS = ['intervals', 'garmin', 'strava'];
+export const STAGING_SCHEMA_VERSION = 1;
+export const rawObjectSchema = z.object({
+    kind: z.literal('raw_object'), schemaVersion: z.literal(STAGING_SCHEMA_VERSION), provider: z.enum(PROVIDERS),
+    endpoint: z.string().min(1), remoteId: z.string().nullable(), fetchedAt: z.string().datetime(),
+    contentHash: z.string().length(64), contentType: z.string().min(1), relativePath: z.string().min(1),
+    scope: z.record(z.string(), z.unknown()).default({}),
+});
+export const runManifestSchema = z.object({
+    kind: z.literal('run_manifest'), schemaVersion: z.literal(STAGING_SCHEMA_VERSION), provider: z.enum(PROVIDERS),
+    runId: z.string().uuid(), fromDate: z.string().date(), createdAt: z.string().datetime(),
+});
+export const sourceEntitySchema = z.object({
+    kind: z.literal('source_entity'), schemaVersion: z.literal(STAGING_SCHEMA_VERSION), provider: z.enum(PROVIDERS),
+    entityType: z.string().min(1), remoteId: z.string().min(1), parentRemoteId: z.string().nullable().default(null),
+    occurredOn: z.string().nullable().default(null), sourceUpdatedAt: z.string().nullable().default(null),
+    rawObjectHash: z.string().length(64).nullable().default(null), payload: z.record(z.string(), z.unknown()),
+    extension: z.record(z.string(), z.unknown()).default({}),
+});
+export const streamManifestSchema = z.object({
+    kind: z.literal('stream_manifest'), schemaVersion: z.literal(STAGING_SCHEMA_VERSION), provider: z.enum(PROVIDERS),
+    activityRemoteId: z.string().min(1), relativePath: z.string().min(1), contentHash: z.string().length(64),
+    rowCount: z.number().int().nonnegative(), startAt: z.string().nullable(), endAt: z.string().nullable(),
+    columns: z.array(z.string()), rawObjectHash: z.string().length(64).nullable().default(null),
+});
+export const activitySyncStateSchema = z.object({
+    kind: z.literal('activity_sync_state'), schemaVersion: z.literal(STAGING_SCHEMA_VERSION), provider: z.enum(PROVIDERS),
+    activityRemoteId: z.string().min(1), summaryHash: z.string().length(64), detailsFetched: z.boolean(),
+});
+export const extractionErrorSchema = z.object({
+    kind: z.literal('extraction_error'), schemaVersion: z.literal(STAGING_SCHEMA_VERSION), provider: z.enum(PROVIDERS),
+    endpoint: z.string().min(1), remoteId: z.string().nullable(), message: z.string().min(1), retryable: z.boolean().default(true),
+});
+export const stagingRecordSchema = z.discriminatedUnion('kind', [runManifestSchema, rawObjectSchema, sourceEntitySchema, streamManifestSchema, activitySyncStateSchema, extractionErrorSchema]);
+//# sourceMappingURL=staging.js.map

package/dist/contracts/storage.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Storage boundary used by Catence core. Implementations may use DuckDB or a
+ * test double, but core logic does not depend on a database driver.
+ */
+export type QueryValues = Record<string, unknown>;
+export type QueryBindings = QueryValues | unknown[];
+export interface ReadDataStore {
+    close(): Promise<void>;
+    rows<T extends Record<string, unknown>>(sql: string, values?: QueryBindings): Promise<T[]>;
+    tableNames(query: string): Promise<string[]>;
+    interrupt(): void;
+}
+export interface WriteDataStore extends ReadDataStore {
+    run(sql: string, values?: QueryBindings): Promise<void>;
+}

package/dist/contracts/storage.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=storage.js.map

package/dist/core/dashboard/snapshot.d.ts

@@ -0,0 +1,16 @@
+import type { ReadOnlyRepository } from '../query/repository.js';
+export type DashboardOptions = {
+    endDate: string;
+    days: number;
+};
+/**
+ * Fixed dashboard facts for the local Console.
+ *
+ * The service deliberately reads Catence's existing canonical projections
+ * instead of adding a visualization-specific store or materialized mirror.
+ */
+export declare class DashboardSnapshotService {
+    private readonly repository;
+    constructor(repository: ReadOnlyRepository);
+    snapshot(options: DashboardOptions): Promise<Record<string, unknown>>;
+}