@duetso/agent 0.1.53 → 0.1.55

package/dist/src/memory/embedding.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Client for the Duet embedding endpoint.
+ *
+ * Routes through the Duet public API (`POST <app>/api/v1/embed`) gated
+ * by the user's existing `DUET_API_KEY`. Logged-in users get embeddings
+ * for free as a CLI perk; we deliberately do not expose a way to plug
+ * in a different provider key here so the runtime stays single-path.
+ *
+ * Behavior:
+ *   - Inputs are batched up to `EMBEDDING_BATCH_LIMIT` per HTTP call so
+ *     a single backfill batch never goes over the request body cap.
+ *   - 5xx responses and network errors retry with exponential backoff;
+ *     4xx responses (auth, malformed) fail fast since retrying will not
+ *     change the outcome.
+ *   - When `DUET_API_KEY` is missing the function throws a typed error
+ *     so callers can degrade to keyword-only retrieval (the recall_memory
+ *     tool catches it and logs once; the backfill worker logs and
+ *     sleeps until the user logs in).
+ */
+/** Default embedding model identifier sent with every request. */
+export declare const DEFAULT_EMBEDDING_MODEL = "openai/text-embedding-3-small";
+/** Maximum input strings sent in a single embedding request. */
+export declare const EMBEDDING_BATCH_LIMIT = 100;
+/**
+ * Callable shape consumed by the backfill worker and the recall_memory
+ * tool. Inputs map 1:1 to output vectors.
+ */
+export type EmbedFn = (inputs: string[]) => Promise<number[][]>;
+export declare class EmbeddingUnavailableError extends Error {
+    constructor(message: string);
+}
+export interface CreateEmbeddingClientOptions {
+    /** Embedding model identifier sent with each request. */
+    model?: string;
+    /**
+     * Override the API key resolver. Defaults to reading `DUET_API_KEY`
+     * from `process.env`. Tests inject a fixed value to exercise the
+     * client without touching environment state.
+     */
+    apiKey?: string | (() => string | undefined);
+    /**
+     * Override the base URL. Defaults to `resolveDuetAppBaseUrl()` so the
+     * client follows the same staging/production routing as the rest of
+     * the CLI.
+     */
+    baseUrl?: string;
+    /**
+     * Override the fetch implementation. Tests use this to assert request
+     * shape and stub responses without standing up a real server.
+     */
+    fetch?: typeof fetch;
+}
+/**
+ * Build an `EmbedFn` bound to the Duet embedding endpoint. Constructed
+ * once per process and reused for every backfill batch and every
+ * `recall_memory` query so connection reuse can amortize TLS setup.
+ */
+export declare function createEmbeddingClient(options?: CreateEmbeddingClientOptions): EmbedFn;
+//# sourceMappingURL=embedding.d.ts.map

package/dist/src/memory/embedding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding.d.ts","sourceRoot":"","sources":["../../../src/memory/embedding.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,kEAAkE;AAClE,eAAO,MAAM,uBAAuB,kCAAkC,CAAC;AACvE,gEAAgE;AAChE,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAMzC;;;GAGG;AACH,MAAM,MAAM,OAAO,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AAEhE,qBAAa,yBAA0B,SAAQ,KAAK;gBACtC,OAAO,EAAE,MAAM;CAI5B;AAED,MAAM,WAAW,4BAA4B;IAC3C,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,GAAG,SAAS,CAAC,CAAC;IAC7C;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,GAAE,4BAAiC,GAAG,OAAO,CAmCzF"}

package/dist/src/memory/embedding.js

@@ -0,0 +1,126 @@
+import { resolveDuetAppBaseUrl } from "../lib/duet-app-url.js";
+/**
+ * Client for the Duet embedding endpoint.
+ *
+ * Routes through the Duet public API (`POST <app>/api/v1/embed`) gated
+ * by the user's existing `DUET_API_KEY`. Logged-in users get embeddings
+ * for free as a CLI perk; we deliberately do not expose a way to plug
+ * in a different provider key here so the runtime stays single-path.
+ *
+ * Behavior:
+ *   - Inputs are batched up to `EMBEDDING_BATCH_LIMIT` per HTTP call so
+ *     a single backfill batch never goes over the request body cap.
+ *   - 5xx responses and network errors retry with exponential backoff;
+ *     4xx responses (auth, malformed) fail fast since retrying will not
+ *     change the outcome.
+ *   - When `DUET_API_KEY` is missing the function throws a typed error
+ *     so callers can degrade to keyword-only retrieval (the recall_memory
+ *     tool catches it and logs once; the backfill worker logs and
+ *     sleeps until the user logs in).
+ */
+/** Default embedding model identifier sent with every request. */
+export const DEFAULT_EMBEDDING_MODEL = "openai/text-embedding-3-small";
+/** Maximum input strings sent in a single embedding request. */
+export const EMBEDDING_BATCH_LIMIT = 100;
+const ENDPOINT_PATH = "/api/v1/embed";
+const MAX_RETRIES = 3;
+const BASE_BACKOFF_MS = 500;
+export class EmbeddingUnavailableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "EmbeddingUnavailableError";
+    }
+}
+/**
+ * Build an `EmbedFn` bound to the Duet embedding endpoint. Constructed
+ * once per process and reused for every backfill batch and every
+ * `recall_memory` query so connection reuse can amortize TLS setup.
+ */
+export function createEmbeddingClient(options = {}) {
+    const model = options.model ?? DEFAULT_EMBEDDING_MODEL;
+    const baseUrl = options.baseUrl ?? resolveDuetAppBaseUrl();
+    const fetchImpl = options.fetch ?? fetch;
+    return async (inputs) => {
+        if (inputs.length === 0)
+            return [];
+        const apiKey = resolveApiKey(options.apiKey);
+        if (!apiKey) {
+            // Throwing a typed error lets callers branch on graceful
+            // degradation without string-matching the message.
+            throw new EmbeddingUnavailableError("DUET_API_KEY is not set; embeddings unavailable. Run `duet login` to enable hybrid memory retrieval.");
+        }
+        const results = [];
+        for (let offset = 0; offset < inputs.length; offset += EMBEDDING_BATCH_LIMIT) {
+            const slice = inputs.slice(offset, offset + EMBEDDING_BATCH_LIMIT);
+            const vectors = await postBatch({
+                url: `${baseUrl}${ENDPOINT_PATH}`,
+                apiKey,
+                model,
+                inputs: slice,
+                fetchImpl,
+            });
+            if (vectors.length !== slice.length) {
+                throw new Error(`Embedding response length (${vectors.length}) did not match request size (${slice.length})`);
+            }
+            results.push(...vectors);
+        }
+        return results;
+    };
+}
+async function postBatch(options) {
+    let lastError;
+    for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+        try {
+            const response = await options.fetchImpl(options.url, {
+                method: "POST",
+                headers: {
+                    authorization: `Bearer ${options.apiKey}`,
+                    "content-type": "application/json",
+                },
+                body: JSON.stringify({ input: options.inputs, model: options.model }),
+            });
+            if (response.ok) {
+                const body = (await response.json());
+                return body.embeddings;
+            }
+            // 4xx errors (auth, malformed input) will not improve on retry;
+            // surface them immediately so callers see the real cause.
+            if (response.status >= 400 && response.status < 500) {
+                const detail = await safeReadText(response);
+                throw new EmbeddingUnavailableError(`Embedding endpoint returned ${response.status}: ${detail}`);
+            }
+            lastError = new Error(`Embedding endpoint returned ${response.status}`);
+        }
+        catch (error) {
+            // Re-throw typed errors immediately; only retry on transport-level failures.
+            if (error instanceof EmbeddingUnavailableError)
+                throw error;
+            lastError = error;
+        }
+        if (attempt < MAX_RETRIES - 1) {
+            await sleep(BASE_BACKOFF_MS * 2 ** attempt);
+        }
+    }
+    throw lastError instanceof Error
+        ? lastError
+        : new Error(`Embedding request failed after ${MAX_RETRIES} attempts`);
+}
+function resolveApiKey(override) {
+    if (typeof override === "function")
+        return override();
+    if (typeof override === "string")
+        return override;
+    return process.env.DUET_API_KEY;
+}
+async function safeReadText(response) {
+    try {
+        return await response.text();
+    }
+    catch {
+        return "<unreadable response body>";
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=embedding.js.map

package/dist/src/memory/embedding.js.map

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

package/dist/src/memory/loader.d.ts

@@ -0,0 +1,81 @@
+import type { PGlite } from "@electric-sql/pglite";
+import type { Observation } from "../types/memory.js";
+export interface ScoreInputs {
+    /** Wall-clock time at which scoring is happening. Same value across one ranking pass. */
+    now: number;
+    /** Half-life for the recency exponential decay. Same units as createdAt (milliseconds). */
+    halfLifeMs: number;
+    /** Multiplier applied when an observation is a reflection rather than a raw observation. */
+    reflectionBias: number;
+}
+/**
+ * Combined relevance score used to rank the global layer.
+ *
+ *   score = priorityWeight * recencyDecay * kindBias
+ *
+ * - priorityWeight: 3 / 2 / 1 for high / medium / low.
+ * - recencyDecay: `0.5 ^ (ageMs / halfLifeMs)`. Equals 1.0 at age 0,
+ *   0.5 at one half-life, ~0.0625 at four half-lives. Smooth and
+ *   parameterizable; no cliffs.
+ * - kindBias: `reflectionBias` for reflections, 1.0 for raw
+ *   observations. Default 1.3 keeps reflections preferred at matched
+ *   priority/recency without shutting raw observations out.
+ *
+ * Examples at the default 7d half-life and 1.3 reflection bias:
+ *   - high reflection, 0d:    3 * 1.0    * 1.3 = 3.9
+ *   - high observation, 0d:   3 * 1.0    * 1.0 = 3.0
+ *   - medium reflection, 0d:  2 * 1.0    * 1.3 = 2.6
+ *   - high reflection, 7d:    3 * 0.5    * 1.3 = 1.95
+ *   - low observation, 30d:   1 * 0.0508 * 1.0 = 0.05  (effectively pruned)
+ */
+export declare function score(observation: Observation, inputs: ScoreInputs): number;
+export interface LoadGlobalPackOptions {
+    /**
+     * Session whose rows are excluded from the global pack. The current
+     * runner's session lives in the local pack at full fidelity, so
+     * counting its rows in the global ranking would double-count and
+     * push out cross-session signal. Pass `undefined` to include every
+     * row (e.g. for the `recall_memory` tool when the user wants
+     * unrestricted search).
+     */
+    excludeSessionId?: string;
+    /** Maximum tokens of `content` packed into the result. Defaults to 8000. */
+    tokenBudget?: number;
+    /** Recency half-life in milliseconds. */
+    recencyHalfLifeMs: number;
+    /** Reflection bias multiplier. */
+    reflectionBias: number;
+    /**
+     * Override for `Date.now()`, used by tests so fixture data with
+     * fixed `created_at` values produces deterministic scores.
+     */
+    now?: number;
+}
+/**
+ * Load the highest-scoring rows from every session except the caller's,
+ * up to the token budget. Returns rows ordered by descending score so
+ * the renderer can preserve the ranking visually.
+ *
+ * Implementation note: the database query orders by `created_at DESC`
+ * (cheap with the `idx_obs_kind_priority_created` index) and a generous
+ * over-fetch limit; the actual ranking happens in JS so the recency
+ * decay term can be applied without trying to express `0.5 ^ x` in
+ * portable SQL. With a 8k-token budget and ~250-token rows this means
+ * a worst case of ~32 rows packed; the over-fetch keeps the planner
+ * cheap even when the budget is set higher.
+ */
+export declare function loadGlobalPack(db: PGlite, options: LoadGlobalPackOptions): Promise<Observation[]>;
+export interface LoadLocalPackOptions {
+    sessionId: string;
+}
+/**
+ * Load every row this session produced, ordered chronologically. The
+ * local pack represents the session's own compaction summary — the
+ * observations and reflections that replaced earlier transcript — so
+ * it is rendered whole regardless of size. Bounding the local layer
+ * is the existing observer/reflector pipeline's job: their thresholds
+ * keep this set from unbounded growth, and a reflection condenses it
+ * back down when it gets too large.
+ */
+export declare function loadLocalPack(db: PGlite, options: LoadLocalPackOptions): Promise<Observation[]>;
+//# sourceMappingURL=loader.d.ts.map

package/dist/src/memory/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../../src/memory/loader.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,KAAK,EAAE,WAAW,EAAwC,MAAM,oBAAoB,CAAC;AAmC5F,MAAM,WAAW,WAAW;IAC1B,yFAAyF;IACzF,GAAG,EAAE,MAAM,CAAC;IACZ,2FAA2F;IAC3F,UAAU,EAAE,MAAM,CAAC;IACnB,4FAA4F;IAC5F,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,KAAK,CAAC,WAAW,EAAE,WAAW,EAAE,MAAM,EAAE,WAAW,GAAG,MAAM,CAM3E;AAED,MAAM,WAAW,qBAAqB;IACpC;;;;;;;OAOG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yCAAyC;IACzC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,kCAAkC;IAClC,cAAc,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,cAAc,CAClC,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,WAAW,EAAE,CAAC,CA6DxB;AAED,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CACjC,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,WAAW,EAAE,CAAC,CAUxB"}

package/dist/src/memory/loader.js

@@ -0,0 +1,162 @@
+/**
+ * Loads ranked memory packs for rendering above the message tail.
+ *
+ * The loader splits durable memory into two layers along a single axis —
+ * does the row's session_id match the current runner's session?
+ *
+ *   - Local layer: rows whose session_id equals the current session. The
+ *     current session's compacted view of itself (observations + the
+ *     reflection that may have replaced them). Rendered chronologically
+ *     and unranked because it represents the conversation's own
+ *     compaction summary; reordering it would lose the time signal.
+ *
+ *   - Global layer: every other session's rows, ranked by
+ *     `priority * recencyDecay * kindBias`. Reflections rank higher than
+ *     raw observations through `reflectionBias`. Greedy-fitted to a
+ *     fixed token budget so the prompt prefix stays bounded regardless
+ *     of how big the durable memory database has grown.
+ *
+ * The two layers are intentionally rendered with separate headings so
+ * the model can tell what comes from this conversation versus what
+ * comes from accumulated cross-session knowledge. The render order is
+ * `system prompt -> global -> local -> message history`: the global
+ * pack is the most stable prefix (rebuilt only on compaction), local
+ * is medium-stability (replaced on each reflection), and the message
+ * tail is the only part that grows turn over turn.
+ */
+const PRIORITY_WEIGHT = {
+    high: 3,
+    medium: 2,
+    low: 1,
+};
+/**
+ * Combined relevance score used to rank the global layer.
+ *
+ *   score = priorityWeight * recencyDecay * kindBias
+ *
+ * - priorityWeight: 3 / 2 / 1 for high / medium / low.
+ * - recencyDecay: `0.5 ^ (ageMs / halfLifeMs)`. Equals 1.0 at age 0,
+ *   0.5 at one half-life, ~0.0625 at four half-lives. Smooth and
+ *   parameterizable; no cliffs.
+ * - kindBias: `reflectionBias` for reflections, 1.0 for raw
+ *   observations. Default 1.3 keeps reflections preferred at matched
+ *   priority/recency without shutting raw observations out.
+ *
+ * Examples at the default 7d half-life and 1.3 reflection bias:
+ *   - high reflection, 0d:    3 * 1.0    * 1.3 = 3.9
+ *   - high observation, 0d:   3 * 1.0    * 1.0 = 3.0
+ *   - medium reflection, 0d:  2 * 1.0    * 1.3 = 2.6
+ *   - high reflection, 7d:    3 * 0.5    * 1.3 = 1.95
+ *   - low observation, 30d:   1 * 0.0508 * 1.0 = 0.05  (effectively pruned)
+ */
+export function score(observation, inputs) {
+    const priorityWeight = PRIORITY_WEIGHT[observation.priority];
+    const ageMs = Math.max(0, inputs.now - observation.createdAt);
+    const recencyDecay = Math.pow(0.5, ageMs / inputs.halfLifeMs);
+    const kindBias = observation.kind === "reflection" ? inputs.reflectionBias : 1.0;
+    return priorityWeight * recencyDecay * kindBias;
+}
+/**
+ * Load the highest-scoring rows from every session except the caller's,
+ * up to the token budget. Returns rows ordered by descending score so
+ * the renderer can preserve the ranking visually.
+ *
+ * Implementation note: the database query orders by `created_at DESC`
+ * (cheap with the `idx_obs_kind_priority_created` index) and a generous
+ * over-fetch limit; the actual ranking happens in JS so the recency
+ * decay term can be applied without trying to express `0.5 ^ x` in
+ * portable SQL. With a 8k-token budget and ~250-token rows this means
+ * a worst case of ~32 rows packed; the over-fetch keeps the planner
+ * cheap even when the budget is set higher.
+ */
+export async function loadGlobalPack(db, options) {
+    const tokenBudget = options.tokenBudget ?? 8000;
+    const now = options.now ?? Date.now();
+    // Over-fetch by a comfortable factor so the JS-side scorer has enough
+    // candidates to find the top-N regardless of priority distribution.
+    // 4x the typical row count fitting in the budget keeps the SQL cheap
+    // while leaving headroom for a long tail of low-priority rows.
+    const overFetchLimit = Math.max(200, Math.ceil(tokenBudget / 50));
+    let result;
+    if (options.excludeSessionId === undefined) {
+        result = await db.query(`SELECT id, created_at, session_id, kind, observed_date, referenced_date,
+              relative_date, time_of_day, priority, source_json, content, tags_json
+       FROM observations
+       ORDER BY created_at DESC
+       LIMIT $1`, [overFetchLimit]);
+    }
+    else {
+        // NULL session_id rows (legacy, pre-sessionId tracking) are kept in
+        // the global pool because they cannot match any current session.
+        // Without `IS DISTINCT FROM` Postgres would treat NULL = X as NULL,
+        // which filters those legacy rows out of every query.
+        result = await db.query(`SELECT id, created_at, session_id, kind, observed_date, referenced_date,
+              relative_date, time_of_day, priority, source_json, content, tags_json
+       FROM observations
+       WHERE session_id IS DISTINCT FROM $1
+       ORDER BY created_at DESC
+       LIMIT $2`, [options.excludeSessionId, overFetchLimit]);
+    }
+    const candidates = result.rows.map(rowToObservation);
+    const scoreInputs = {
+        now,
+        halfLifeMs: options.recencyHalfLifeMs,
+        reflectionBias: options.reflectionBias,
+    };
+    const ranked = candidates
+        .map((observation) => ({ observation, score: score(observation, scoreInputs) }))
+        .sort((a, b) => b.score - a.score);
+    const packed = [];
+    let usedTokens = 0;
+    for (const entry of ranked) {
+        const tokens = estimateTokens(entry.observation.content);
+        if (usedTokens + tokens > tokenBudget) {
+            // Skip oversize rows but keep iterating: a smaller row later in
+            // the ranking may still fit, which avoids leaving the budget
+            // half-empty just because one high-scoring row was a long
+            // reflection.
+            continue;
+        }
+        packed.push(entry.observation);
+        usedTokens += tokens;
+    }
+    return packed;
+}
+/**
+ * Load every row this session produced, ordered chronologically. The
+ * local pack represents the session's own compaction summary — the
+ * observations and reflections that replaced earlier transcript — so
+ * it is rendered whole regardless of size. Bounding the local layer
+ * is the existing observer/reflector pipeline's job: their thresholds
+ * keep this set from unbounded growth, and a reflection condenses it
+ * back down when it gets too large.
+ */
+export async function loadLocalPack(db, options) {
+    const result = await db.query(`SELECT id, created_at, session_id, kind, observed_date, referenced_date,
+            relative_date, time_of_day, priority, source_json, content, tags_json
+     FROM observations
+     WHERE session_id = $1
+     ORDER BY created_at ASC`, [options.sessionId]);
+    return result.rows.map(rowToObservation);
+}
+function rowToObservation(row) {
+    return {
+        id: row.id,
+        createdAt: row.created_at,
+        ...(row.session_id !== null ? { sessionId: row.session_id } : {}),
+        kind: row.kind,
+        observedDate: row.observed_date,
+        ...(row.referenced_date !== null ? { referencedDate: row.referenced_date } : {}),
+        ...(row.relative_date !== null ? { relativeDate: row.relative_date } : {}),
+        ...(row.time_of_day !== null ? { timeOfDay: row.time_of_day } : {}),
+        priority: row.priority,
+        source: JSON.parse(row.source_json),
+        content: row.content,
+        tags: JSON.parse(row.tags_json),
+    };
+}
+/** Rough char-to-token estimate matching the rest of the memory subsystem. */
+function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+//# sourceMappingURL=loader.js.map

package/dist/src/memory/loader.js.map

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

package/dist/src/memory/migrations.d.ts

@@ -0,0 +1,54 @@
+import type { PGlite, Transaction } from "@electric-sql/pglite";
+/**
+ * Forward-only schema migrations for the observational memory database.
+ *
+ * Why a real migration framework instead of bare `CREATE TABLE IF NOT
+ * EXISTS`: the memory schema is changing shape (adding `session_id` and
+ * `kind`, dropping `scope`, reshaping `source_json`) and a user upgrading
+ * Duet must have their existing rows transformed in place — dropping the
+ * column without rewriting the data would lose information, and there is
+ * no `duet memory migrate` CLI step we want to require.
+ *
+ * Design notes:
+ *   - Migrations run inside `loadStoredMemory()` and `MemoryDb.open()` so
+ *     both the runner and the `duet memory` CLI see the same upgraded
+ *     schema. Failure aborts startup with a clear message; the underlying
+ *     PGlite directory is also covered by `quarantineDataDirectory()` for
+ *     unreadable cases (see `pglite.ts`).
+ *   - Each migration runs inside a single transaction. Postgres DDL is
+ *     transactional, so a partial failure rolls back to the prior version.
+ *   - The `schema_version` table records every applied migration with its
+ *     wall-clock timestamp. This is read once on open to find the current
+ *     version; we never go backwards.
+ *   - Forward-only by design. A bad migration is fixed by writing the next
+ *     migration, not by reverting. This matches gbrain's pattern after
+ *     they hit "upgrade-wedge" bugs across six schema versions.
+ */
+export interface Migration {
+    /** Monotonic version number. Migrations are applied strictly in ascending order. */
+    version: number;
+    /** One-line summary stored in `schema_version.description` for audit. */
+    description: string;
+    /** Forward step. Receives a transaction so DDL + DML run atomically. */
+    up: (tx: Transaction) => Promise<void>;
+}
+export interface MigrationResult {
+    /** Schema version the database was at before `runMigrations` was called. */
+    fromVersion: number;
+    /** Schema version the database is at after `runMigrations` returns. */
+    toVersion: number;
+    /** Versions actually applied this call (empty when already up to date). */
+    applied: number[];
+}
+/**
+ * Bring the database up to the latest known schema version. Idempotent;
+ * safe to call on every open. Throws on the first failure with the
+ * triggering migration's version in the message so users have a place to
+ * look without grepping.
+ */
+export declare function runMigrations(db: PGlite): Promise<MigrationResult>;
+/** Latest version known to this build. Exported for tests. */
+export declare const LATEST_SCHEMA_VERSION: number;
+/** All registered migrations. Exported for tests. */
+export declare const REGISTERED_MIGRATIONS: readonly Migration[];
+//# sourceMappingURL=migrations.d.ts.map

package/dist/src/memory/migrations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrations.d.ts","sourceRoot":"","sources":["../../../src/memory/migrations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAEhE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,WAAW,SAAS;IACxB,oFAAoF;IACpF,OAAO,EAAE,MAAM,CAAC;IAChB,yEAAyE;IACzE,WAAW,EAAE,MAAM,CAAC;IACpB,wEAAwE;IACxE,EAAE,EAAE,CAAC,EAAE,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC;AAiLD,MAAM,WAAW,eAAe;IAC9B,4EAA4E;IAC5E,WAAW,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,SAAS,EAAE,MAAM,CAAC;IAClB,2EAA2E;IAC3E,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAwCxE;AAED,8DAA8D;AAC9D,eAAO,MAAM,qBAAqB,EAAE,MAAwC,CAAC;AAE7E,qDAAqD;AACrD,eAAO,MAAM,qBAAqB,EAAE,SAAS,SAAS,EAAe,CAAC"}