@meterbility/store-postgres 0.3.1

package/LICENSE

@@ -0,0 +1,33 @@
+MIT License
+
+Copyright (c) 2026 Meterbility authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+----------------------------------------------------------------------
+
+Note: This MIT license covers everything in this repository EXCEPT the
+contents of the /ee directory (when present), which are licensed under the
+Elastic License 2.0 (ELv2) — see /ee/LICENSE.
+
+The /ee directory is reserved for Enterprise Edition modules: multi-tenant
+fleet orchestration, SSO/RBAC, audit logs, and long-retention features.
+
+Nothing under /ee today; the directory is created as a forward-compatible
+marker so the licensing boundary is visible before any /ee code lands.

package/README.md

@@ -0,0 +1,11 @@
+# @meterbility/store-postgres
+
+Part of [Meterbility](https://github.com/HoneycombHairDevelopers/Meterbility) — the debugger for AI agents. Capture every run, inspect every decision, pause and inject live, fork from any step.
+
+Postgres backend for single-operator multi-machine sync. Experimental subset of the SQLite store.
+
+```bash
+npm install @meterbility/store-postgres
+```
+
+See the [Meterbility documentation](https://github.com/HoneycombHairDevelopers/Meterbility#readme) for the full guide. MIT licensed.

package/dist/index.d.ts

@@ -0,0 +1,93 @@
+import { Client } from 'pg';
+import { Run, Step } from '@meterbility/shared';
+import { Store } from '@meterbility/collector';
+
+/**
+ * Async, network-backed equivalent of the SQLite Store. Connects via
+ * the standard `pg` driver. Caller is responsible for `close()` when
+ * done.
+ *
+ * Connection URL precedence:
+ *   1. opts.url
+ *   2. process.env.METERBILITY_DB_URL
+ *   3. process.env.DATABASE_URL
+ *   4. throw
+ */
+declare class PostgresStore {
+    readonly client: Client;
+    private constructor();
+    static open(opts?: {
+        url?: string;
+    }): Promise<PostgresStore>;
+    close(): Promise<void>;
+    /** Convenience for blob storage in Postgres mode (bytea-backed). */
+    putBlob(content: Buffer | string, ref: string): Promise<void>;
+    getBlob(ref: string): Promise<Buffer | undefined>;
+    getBlobString(ref: string): Promise<string | undefined>;
+}
+
+/**
+ * Postgres schema mirroring `@meterbility/collector` (SQLite). Same column
+ * names, same semantics. Differences:
+ *   - JSON columns use `jsonb` (queryable + indexable later).
+ *   - Timestamps use `timestamptz` rather than free-form text.
+ *   - Indexes are explicit; SQLite's `WAL` / `synchronous` pragmas have
+ *     no Postgres equivalent and aren't applied.
+ *
+ * Designed for Meterbility's hosted/team tier (SPEC §15.3). Local mode keeps
+ * the SQLite store as default; this exists for the deployments where
+ * multiple operators share a project's run history.
+ */
+/**
+ * Version history (mirrors `@meterbility/collector` SCHEMA_VERSION):
+ *   v3 → v4 — file_change + baseline_tree tables, runs.baseline_tree_id,
+ *             runs.probe_state. Per v0.3 §3.3, full enum coverage in
+ *             CHECK constraints up front so v0.4 / v0.5 don't need
+ *             migrations as new derived_from / op values come online.
+ *             Additive-only per v0.2 §17.
+ */
+declare const POSTGRES_SCHEMA_VERSION = 4;
+declare function ensurePostgresSchema(client: Client): Promise<void>;
+
+declare function pgUpsertProject(store: PostgresStore, cwd: string, name?: string): Promise<{
+    project_id: string;
+    cwd: string;
+    name: string;
+}>;
+declare function pgUpsertAgent(store: PostgresStore, projectId: string, name: string): Promise<{
+    agent_id: string;
+    project_id: string;
+    name: string;
+}>;
+declare function pgInsertRun(store: PostgresStore, run: Run): Promise<void>;
+declare function pgInsertStep(store: PostgresStore, step: Step): Promise<void>;
+declare function pgListRuns(store: PostgresStore, opts?: {
+    limit?: number;
+    projectId?: string;
+}): Promise<Run[]>;
+declare function pgGetRun(store: PostgresStore, runId: string): Promise<Run | undefined>;
+declare function pgListSteps(store: PostgresStore, runId: string): Promise<Step[]>;
+
+/**
+ * Copy a local SQLite Store's data into a Postgres deployment. The
+ * intended use case (SPEC §15.3): a team operator wants to share a
+ * project's run history with teammates without giving up the local
+ * dogfood loop.
+ *
+ * Idempotent — re-running won't duplicate rows because every insert
+ * uses ON CONFLICT DO UPDATE.
+ *
+ * Sync order: projects → agents → runs → steps → blobs (referenced by
+ * step rows and run rows).
+ */
+interface SyncReport {
+    runs: number;
+    steps: number;
+    blobs: number;
+    bytes: number;
+}
+declare function syncSqliteToPostgres(sqlite: Store, postgres: PostgresStore, opts?: {
+    limitRuns?: number;
+}): Promise<SyncReport>;
+
+export { POSTGRES_SCHEMA_VERSION, PostgresStore, type SyncReport, ensurePostgresSchema, pgGetRun, pgInsertRun, pgInsertStep, pgListRuns, pgListSteps, pgUpsertAgent, pgUpsertProject, syncSqliteToPostgres };

package/dist/index.js

@@ -0,0 +1,530 @@
+// src/store.ts
+import pg from "pg";
+
+// src/schema.ts
+var POSTGRES_SCHEMA_VERSION = 4;
+async function ensurePostgresSchema(client) {
+  await client.query(`
+    CREATE TABLE IF NOT EXISTS meta (
+      key TEXT PRIMARY KEY,
+      value TEXT NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS projects (
+      project_id TEXT PRIMARY KEY,
+      name TEXT NOT NULL,
+      cwd TEXT NOT NULL UNIQUE,
+      created_at TIMESTAMPTZ NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS agents (
+      agent_id TEXT PRIMARY KEY,
+      project_id TEXT NOT NULL REFERENCES projects(project_id),
+      name TEXT NOT NULL,
+      created_at TIMESTAMPTZ NOT NULL,
+      UNIQUE(project_id, name)
+    );
+
+    CREATE TABLE IF NOT EXISTS runs (
+      run_id TEXT PRIMARY KEY,
+      agent_id TEXT NOT NULL REFERENCES agents(agent_id),
+      project_id TEXT NOT NULL REFERENCES projects(project_id),
+      source_session_id TEXT,
+      source_runtime TEXT NOT NULL,
+      title TEXT,
+      status TEXT NOT NULL,
+      started_at TIMESTAMPTZ NOT NULL,
+      ended_at TIMESTAMPTZ,
+      git_branch TEXT,
+      cwd TEXT,
+      fork_origin_run_id TEXT REFERENCES runs(run_id),
+      fork_origin_step_id TEXT,
+      tokens_total_input BIGINT NOT NULL DEFAULT 0,
+      tokens_total_output BIGINT NOT NULL DEFAULT 0,
+      tokens_total_cached BIGINT NOT NULL DEFAULT 0,
+      cost_cents DOUBLE PRECISION NOT NULL DEFAULT 0,
+      step_count INTEGER NOT NULL DEFAULT 0,
+      tags JSONB NOT NULL DEFAULT '[]'::jsonb
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_runs_project_started
+      ON runs(project_id, started_at DESC);
+    CREATE INDEX IF NOT EXISTS idx_runs_session
+      ON runs(source_session_id);
+    CREATE INDEX IF NOT EXISTS idx_runs_fork_origin
+      ON runs(fork_origin_run_id);
+
+    CREATE TABLE IF NOT EXISTS steps (
+      step_id TEXT PRIMARY KEY,
+      run_id TEXT NOT NULL REFERENCES runs(run_id) ON DELETE CASCADE,
+      parent_step_id TEXT,
+      fork_origin_id TEXT,
+      sequence INTEGER NOT NULL,
+      timestamp TIMESTAMPTZ NOT NULL,
+      model TEXT NOT NULL,
+      context_snapshot_id TEXT NOT NULL,
+      decision_ref TEXT NOT NULL,
+      action JSONB NOT NULL,
+      outcome JSONB NOT NULL,
+      tokens_input BIGINT NOT NULL DEFAULT 0,
+      tokens_output BIGINT NOT NULL DEFAULT 0,
+      tokens_cached_read BIGINT NOT NULL DEFAULT 0,
+      tokens_cache_creation BIGINT NOT NULL DEFAULT 0,
+      tokens_cache_creation_1h BIGINT NOT NULL DEFAULT 0,
+      tokens_reasoning BIGINT,
+      latency_ms INTEGER NOT NULL DEFAULT 0,
+      cost_cents DOUBLE PRECISION NOT NULL DEFAULT 0,
+      status TEXT NOT NULL,
+      tags JSONB NOT NULL DEFAULT '[]'::jsonb,
+      UNIQUE(run_id, sequence)
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_steps_run
+      ON steps(run_id, sequence);
+    CREATE INDEX IF NOT EXISTS idx_steps_context
+      ON steps(context_snapshot_id);
+
+    CREATE TABLE IF NOT EXISTS context_snapshots (
+      snapshot_id TEXT PRIMARY KEY,
+      blob_ref TEXT NOT NULL,
+      component_count INTEGER NOT NULL DEFAULT 0,
+      created_at TIMESTAMPTZ NOT NULL
+    );
+
+    -- Blob content is stored inline as bytea in Postgres mode (no
+    -- separate filesystem layer). Use BlobStore.put / .get on the store.
+    CREATE TABLE IF NOT EXISTS blobs (
+      blob_ref TEXT PRIMARY KEY,
+      content BYTEA NOT NULL,
+      created_at TIMESTAMPTZ NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS forks (
+      fork_id TEXT PRIMARY KEY,
+      origin_run_id TEXT NOT NULL REFERENCES runs(run_id),
+      origin_step_id TEXT NOT NULL,
+      fork_run_id TEXT NOT NULL REFERENCES runs(run_id),
+      edit_type TEXT NOT NULL,
+      edit_payload JSONB NOT NULL,
+      created_at TIMESTAMPTZ NOT NULL
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_forks_origin
+      ON forks(origin_run_id);
+
+    CREATE TABLE IF NOT EXISTS annotations (
+      annotation_id TEXT PRIMARY KEY,
+      target_kind TEXT NOT NULL,
+      target_id TEXT NOT NULL,
+      author TEXT NOT NULL,
+      verdict TEXT,
+      note TEXT,
+      created_at TIMESTAMPTZ NOT NULL
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_annotations_target
+      ON annotations(target_kind, target_id);
+
+    CREATE TABLE IF NOT EXISTS regression_tests (
+      test_id TEXT PRIMARY KEY,
+      name TEXT NOT NULL UNIQUE,
+      description TEXT,
+      assertions JSONB NOT NULL,
+      canonical_run_id TEXT REFERENCES runs(run_id),
+      created_at TIMESTAMPTZ NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS regression_results (
+      result_id TEXT PRIMARY KEY,
+      test_id TEXT NOT NULL REFERENCES regression_tests(test_id) ON DELETE CASCADE,
+      run_id TEXT NOT NULL REFERENCES runs(run_id) ON DELETE CASCADE,
+      passed BOOLEAN NOT NULL,
+      details JSONB NOT NULL,
+      created_at TIMESTAMPTZ NOT NULL
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_regression_results_test
+      ON regression_results(test_id, created_at DESC);
+
+    -- \u2500\u2500\u2500 v0.3 Track A: per-step file change capture (mirror) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+    -- See packages/collector/src/schema.ts for the design rationale.
+    CREATE TABLE IF NOT EXISTS file_change (
+      file_change_id      TEXT PRIMARY KEY,
+      run_id              TEXT NOT NULL REFERENCES runs(run_id) ON DELETE CASCADE,
+      step_id             TEXT NOT NULL REFERENCES steps(step_id) ON DELETE CASCADE,
+      sequence            INTEGER NOT NULL,
+      tool_call_id        TEXT,
+      derived_from        TEXT NOT NULL
+        CHECK (derived_from IN ('tool_call','filesystem_watch','git_diff')),
+      path                TEXT NOT NULL,
+      old_path            TEXT,
+      op                  TEXT NOT NULL
+        CHECK (op IN ('create','modify','delete','rename','chmod')),
+      before_blob_ref     TEXT,
+      after_blob_ref      TEXT,
+      partial_diff        BOOLEAN NOT NULL DEFAULT FALSE,
+      gitignored          BOOLEAN NOT NULL DEFAULT FALSE,
+      patch_text          TEXT,
+      patch_format        TEXT
+        CHECK (patch_format IN ('unified','binary','notebook_cell')
+               OR patch_format IS NULL),
+      encoding            TEXT,
+      bom                 BOOLEAN NOT NULL DEFAULT FALSE,
+      line_endings        TEXT,
+      mime                TEXT,
+      language            TEXT,
+      size_before         BIGINT,
+      size_after          BIGINT,
+      line_count_before   INTEGER,
+      line_count_after    INTEGER,
+      lines_added         INTEGER NOT NULL DEFAULT 0,
+      lines_removed       INTEGER NOT NULL DEFAULT 0,
+      mode_before         INTEGER,
+      mode_after          INTEGER,
+      source_tool_name    TEXT,
+      source_tool_input   JSONB,
+      redacted            BOOLEAN NOT NULL DEFAULT FALSE,
+      normalizer_notes    JSONB,
+      created_at          TIMESTAMPTZ NOT NULL,
+      UNIQUE(step_id, sequence)
+    );
+    CREATE INDEX IF NOT EXISTS idx_fc_run_step
+      ON file_change(run_id, step_id);
+    CREATE INDEX IF NOT EXISTS idx_fc_run_path
+      ON file_change(run_id, path);
+    CREATE INDEX IF NOT EXISTS idx_fc_step
+      ON file_change(step_id);
+    CREATE INDEX IF NOT EXISTS idx_fc_path_seq
+      ON file_change(run_id, path, step_id);
+
+    -- \u2500\u2500\u2500 v0.3 Track A: baseline working tree (mirror) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+    CREATE TABLE IF NOT EXISTS baseline_tree (
+      baseline_tree_id    TEXT PRIMARY KEY,
+      project_id          TEXT NOT NULL REFERENCES projects(project_id),
+      manifest_blob_ref   TEXT NOT NULL,
+      git_head            TEXT,
+      git_dirty           BOOLEAN NOT NULL DEFAULT FALSE,
+      captured_at         TIMESTAMPTZ NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_bt_project
+      ON baseline_tree(project_id);
+    CREATE INDEX IF NOT EXISTS idx_bt_git
+      ON baseline_tree(project_id, git_head);
+  `);
+  await client.query(
+    "ALTER TABLE steps ADD COLUMN IF NOT EXISTS tokens_cache_creation_1h BIGINT NOT NULL DEFAULT 0"
+  );
+  await client.query(
+    "ALTER TABLE runs ADD COLUMN IF NOT EXISTS baseline_tree_id TEXT"
+  );
+  await client.query(
+    "ALTER TABLE runs ADD COLUMN IF NOT EXISTS probe_state TEXT"
+  );
+  const versionRow = await client.query(
+    "SELECT value FROM meta WHERE key = 'schema_version'"
+  );
+  if (versionRow.rowCount === 0) {
+    await client.query(
+      "INSERT INTO meta(key,value) VALUES ($1,$2)",
+      ["schema_version", String(POSTGRES_SCHEMA_VERSION)]
+    );
+  } else if (Number(versionRow.rows[0].value) < POSTGRES_SCHEMA_VERSION) {
+    await client.query(
+      "UPDATE meta SET value = $1 WHERE key = 'schema_version'",
+      [String(POSTGRES_SCHEMA_VERSION)]
+    );
+  }
+}
+
+// src/store.ts
+var PostgresStore = class _PostgresStore {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  static async open(opts) {
+    const url = opts?.url ?? process.env.METERBILITY_DB_URL ?? process.env.DATABASE_URL;
+    if (!url) {
+      throw new Error(
+        "PostgresStore requires a connection URL. Pass opts.url or set METERBILITY_DB_URL."
+      );
+    }
+    const client = new pg.Client({ connectionString: url });
+    await client.connect();
+    await ensurePostgresSchema(client);
+    return new _PostgresStore(client);
+  }
+  async close() {
+    await this.client.end();
+  }
+  /** Convenience for blob storage in Postgres mode (bytea-backed). */
+  async putBlob(content, ref) {
+    const buf = typeof content === "string" ? Buffer.from(content, "utf-8") : content;
+    await this.client.query(
+      `INSERT INTO blobs(blob_ref, content, created_at)
+       VALUES ($1, $2, NOW())
+       ON CONFLICT (blob_ref) DO NOTHING`,
+      [ref, buf]
+    );
+  }
+  async getBlob(ref) {
+    const r = await this.client.query(
+      "SELECT content FROM blobs WHERE blob_ref = $1",
+      [ref]
+    );
+    return r.rows[0]?.content;
+  }
+  async getBlobString(ref) {
+    const buf = await this.getBlob(ref);
+    return buf ? buf.toString("utf-8") : void 0;
+  }
+};
+
+// src/queries.ts
+function rowToRun(r) {
+  return {
+    run_id: r.run_id,
+    agent_id: r.agent_id,
+    project_id: r.project_id,
+    source_session_id: r.source_session_id ?? void 0,
+    source_runtime: r.source_runtime,
+    title: r.title ?? void 0,
+    status: r.status,
+    started_at: r.started_at.toISOString(),
+    ended_at: r.ended_at?.toISOString() ?? void 0,
+    git_branch: r.git_branch ?? void 0,
+    cwd: r.cwd ?? void 0,
+    fork_origin_run_id: r.fork_origin_run_id ?? void 0,
+    fork_origin_step_id: r.fork_origin_step_id ?? void 0,
+    tokens_total_input: Number(r.tokens_total_input),
+    tokens_total_output: Number(r.tokens_total_output),
+    tokens_total_cached: Number(r.tokens_total_cached),
+    cost_cents: Number(r.cost_cents),
+    step_count: r.step_count,
+    tags: Array.isArray(r.tags) ? r.tags : []
+  };
+}
+function rowToStep(r) {
+  return {
+    step_id: r.step_id,
+    run_id: r.run_id,
+    parent_step_id: r.parent_step_id ?? void 0,
+    fork_origin_id: r.fork_origin_id ?? void 0,
+    sequence: r.sequence,
+    timestamp: r.timestamp.toISOString(),
+    model: r.model,
+    context_snapshot_id: r.context_snapshot_id,
+    decision_ref: r.decision_ref,
+    action: r.action,
+    outcome: r.outcome,
+    tokens: {
+      input: Number(r.tokens_input),
+      output: Number(r.tokens_output),
+      cached_read: Number(r.tokens_cached_read),
+      cache_creation: Number(r.tokens_cache_creation),
+      cache_creation_1h: Number(r.tokens_cache_creation_1h ?? 0),
+      reasoning: r.tokens_reasoning != null ? Number(r.tokens_reasoning) : void 0
+    },
+    latency_ms: r.latency_ms,
+    cost_cents: Number(r.cost_cents),
+    tags: Array.isArray(r.tags) ? r.tags : [],
+    status: r.status
+  };
+}
+async function pgUpsertProject(store, cwd, name) {
+  const existing = await store.client.query("SELECT project_id, cwd, name FROM projects WHERE cwd = $1", [cwd]);
+  if (existing.rowCount && existing.rowCount > 0) return existing.rows[0];
+  const id = `prj_${cryptoRandom()}`;
+  const display = name ?? cwd.split("/").pop() ?? cwd;
+  await store.client.query(
+    "INSERT INTO projects(project_id, name, cwd, created_at) VALUES ($1,$2,$3,NOW())",
+    [id, display, cwd]
+  );
+  return { project_id: id, cwd, name: display };
+}
+async function pgUpsertAgent(store, projectId, name) {
+  const existing = await store.client.query(
+    "SELECT agent_id, project_id, name FROM agents WHERE project_id = $1 AND name = $2",
+    [projectId, name]
+  );
+  if (existing.rowCount && existing.rowCount > 0) return existing.rows[0];
+  const id = `agt_${cryptoRandom()}`;
+  await store.client.query(
+    "INSERT INTO agents(agent_id, project_id, name, created_at) VALUES ($1,$2,$3,NOW())",
+    [id, projectId, name]
+  );
+  return { agent_id: id, project_id: projectId, name };
+}
+async function pgInsertRun(store, run) {
+  await store.client.query(
+    `INSERT INTO runs(
+       run_id, agent_id, project_id, source_session_id, source_runtime,
+       title, status, started_at, ended_at, git_branch, cwd,
+       fork_origin_run_id, fork_origin_step_id,
+       tokens_total_input, tokens_total_output, tokens_total_cached,
+       cost_cents, step_count, tags
+     ) VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13,$14,$15,$16,$17,$18,$19::jsonb)
+     ON CONFLICT (run_id) DO UPDATE SET
+       status = EXCLUDED.status,
+       ended_at = EXCLUDED.ended_at,
+       tokens_total_input = EXCLUDED.tokens_total_input,
+       tokens_total_output = EXCLUDED.tokens_total_output,
+       tokens_total_cached = EXCLUDED.tokens_total_cached,
+       cost_cents = EXCLUDED.cost_cents,
+       step_count = EXCLUDED.step_count,
+       tags = EXCLUDED.tags`,
+    [
+      run.run_id,
+      run.agent_id,
+      run.project_id,
+      run.source_session_id ?? null,
+      run.source_runtime,
+      run.title ?? null,
+      run.status,
+      run.started_at,
+      run.ended_at ?? null,
+      run.git_branch ?? null,
+      run.cwd ?? null,
+      run.fork_origin_run_id ?? null,
+      run.fork_origin_step_id ?? null,
+      run.tokens_total_input,
+      run.tokens_total_output,
+      run.tokens_total_cached,
+      run.cost_cents,
+      run.step_count,
+      JSON.stringify(run.tags ?? [])
+    ]
+  );
+}
+async function pgInsertStep(store, step) {
+  await store.client.query(
+    `INSERT INTO steps(
+       step_id, run_id, parent_step_id, fork_origin_id, sequence, timestamp,
+       model, context_snapshot_id, decision_ref, action, outcome,
+       tokens_input, tokens_output, tokens_cached_read, tokens_cache_creation,
+       tokens_cache_creation_1h, tokens_reasoning, latency_ms, cost_cents,
+       status, tags
+     ) VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10::jsonb,$11::jsonb,$12,$13,$14,$15,$16,$17,$18,$19,$20,$21::jsonb)
+     ON CONFLICT (step_id) DO UPDATE SET
+       action = EXCLUDED.action,
+       outcome = EXCLUDED.outcome,
+       tokens_input = EXCLUDED.tokens_input,
+       tokens_output = EXCLUDED.tokens_output,
+       tokens_cached_read = EXCLUDED.tokens_cached_read,
+       tokens_cache_creation = EXCLUDED.tokens_cache_creation,
+       tokens_cache_creation_1h = EXCLUDED.tokens_cache_creation_1h,
+       tokens_reasoning = EXCLUDED.tokens_reasoning,
+       latency_ms = EXCLUDED.latency_ms,
+       cost_cents = EXCLUDED.cost_cents,
+       status = EXCLUDED.status,
+       tags = EXCLUDED.tags`,
+    [
+      step.step_id,
+      step.run_id,
+      step.parent_step_id ?? null,
+      step.fork_origin_id ?? null,
+      step.sequence,
+      step.timestamp,
+      step.model,
+      step.context_snapshot_id,
+      step.decision_ref,
+      JSON.stringify(step.action),
+      JSON.stringify(step.outcome),
+      step.tokens.input,
+      step.tokens.output,
+      step.tokens.cached_read,
+      step.tokens.cache_creation,
+      step.tokens.cache_creation_1h ?? 0,
+      step.tokens.reasoning ?? null,
+      step.latency_ms,
+      step.cost_cents,
+      step.status,
+      JSON.stringify(step.tags ?? [])
+    ]
+  );
+}
+async function pgListRuns(store, opts = {}) {
+  const params = [];
+  let where = "1=1";
+  if (opts.projectId) {
+    params.push(opts.projectId);
+    where += ` AND project_id = $${params.length}`;
+  }
+  params.push(opts.limit ?? 50);
+  const r = await store.client.query(
+    `SELECT * FROM runs WHERE ${where} ORDER BY started_at DESC LIMIT $${params.length}`,
+    params
+  );
+  return r.rows.map(rowToRun);
+}
+async function pgGetRun(store, runId) {
+  const r = await store.client.query(
+    "SELECT * FROM runs WHERE run_id = $1 OR run_id LIKE $2 LIMIT 2",
+    [runId, `${runId}%`]
+  );
+  return r.rowCount === 1 ? rowToRun(r.rows[0]) : void 0;
+}
+async function pgListSteps(store, runId) {
+  const r = await store.client.query(
+    "SELECT * FROM steps WHERE run_id = $1 ORDER BY sequence ASC",
+    [runId]
+  );
+  return r.rows.map(rowToStep);
+}
+function cryptoRandom() {
+  const arr = new Uint8Array(8);
+  for (let i = 0; i < 8; i++) arr[i] = Math.floor(Math.random() * 256);
+  return Array.from(arr, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+// src/sync.ts
+import { listRuns, listSteps, resolveSnapshotBlobRef } from "@meterbility/collector";
+async function syncSqliteToPostgres(sqlite, postgres, opts = {}) {
+  const runs = listRuns(sqlite, { limit: opts.limitRuns ?? 1e3 });
+  const report = { runs: 0, steps: 0, blobs: 0, bytes: 0 };
+  for (const run of runs) {
+    const proj = await pgUpsertProject(
+      postgres,
+      run.cwd ?? "(unknown)",
+      run.cwd ?? void 0
+    );
+    const agent = await pgUpsertAgent(postgres, proj.project_id, "synced");
+    const remappedRun = {
+      ...run,
+      project_id: proj.project_id,
+      agent_id: agent.agent_id
+    };
+    await pgInsertRun(postgres, remappedRun);
+    report.runs += 1;
+    const steps = listSteps(sqlite, run.run_id);
+    for (const step of steps) {
+      await pgInsertStep(postgres, { ...step, run_id: remappedRun.run_id });
+      report.steps += 1;
+      const refs = /* @__PURE__ */ new Set();
+      refs.add(resolveSnapshotBlobRef(sqlite, step.context_snapshot_id));
+      refs.add(step.decision_ref);
+      if (step.outcome.tool_result_ref) refs.add(step.outcome.tool_result_ref);
+      for (const r of refs) {
+        const buf = await sqlite.blobs.getBuffer(r).catch(() => void 0);
+        if (!buf) continue;
+        await postgres.putBlob(buf, r);
+        report.blobs += 1;
+        report.bytes += buf.length;
+      }
+    }
+  }
+  return report;
+}
+export {
+  POSTGRES_SCHEMA_VERSION,
+  PostgresStore,
+  ensurePostgresSchema,
+  pgGetRun,
+  pgInsertRun,
+  pgInsertStep,
+  pgListRuns,
+  pgListSteps,
+  pgUpsertAgent,
+  pgUpsertProject,
+  syncSqliteToPostgres
+};

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@meterbility/store-postgres",
+  "version": "0.3.1",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@meterbility/shared": "^0.3.0",
+    "@meterbility/spec": "^0.3.0",
+    "pg": "^8.13.0",
+    "@meterbility/collector": "^0.3.0"
+  },
+  "devDependencies": {
+    "@types/pg": "^8.11.0"
+  },
+  "description": "Postgres backend for Meterbility (single-operator multi-machine sync)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HoneycombHairDevelopers/Meterbility.git",
+    "directory": "packages/store-postgres"
+  },
+  "homepage": "https://github.com/HoneycombHairDevelopers/Meterbility#readme",
+  "bugs": {
+    "url": "https://github.com/HoneycombHairDevelopers/Meterbility/issues"
+  },
+  "engines": {
+    "node": ">=20.6"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "types": "dist/index.d.ts",
+  "tsup": {
+    "entry": [
+      "src/index.ts"
+    ],
+    "format": [
+      "esm"
+    ],
+    "dts": true,
+    "clean": true
+  },
+  "scripts": {
+    "build": "tsup"
+  }
+}