@retinue/agentkit 0.1.0

package/dist/adapters/postgres/migrations.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Versioned, reversible migrations. Each `up`/`down` is a list of single statements so any
+ * `SqlExecutor` (node-postgres or PGlite) applies them identically. `migrate` applies in order;
+ * `rollback` reverses.
+ */
+import type { SqlExecutor } from "./sql.js";
+export type Migration = {
+    readonly id: string;
+    readonly up: readonly string[];
+    readonly down: readonly string[];
+};
+export declare const MIGRATIONS: readonly Migration[];
+/**
+ * pgvector migrations, applied separately (#135).
+ *
+ * **Not in `MIGRATIONS`,** and that is deliberate. `CREATE EXTENSION vector` fails on a Postgres without
+ * pgvector installed — including PGlite, which the conformance suite runs against by default — so folding
+ * these into the main list would make every test require an extension most deployments install explicitly
+ * anyway. `migrateVector` is called by a deployment that has it, and `hasVectorExtension` tells a caller
+ * whether it does rather than making them guess from an error.
+ *
+ * **Dimensions are fixed at 1536.** pgvector's `vector(N)` needs a literal, and an index cannot span
+ * dimensions, so a deployment changing embedding model *sizes* re-migrates rather than re-indexing —
+ * which is why `EmbeddingModelRef` carries `dimensions` and `listStaleSources` compares it.
+ */
+export declare const VECTOR_DIMENSIONS = 1536;
+/**
+ * The index: HNSW, not IVFFlat.
+ *
+ * The benchmark the SPEC asks for, stated rather than implied. HNSW builds slower and uses more memory;
+ * IVFFlat needs a representative sample at build time and degrades badly when the data grows past what it was
+ * trained on. For a multi-tenant knowledge base where every tenant's corpus grows continuously and unevenly,
+ * a list-based index has to be periodically rebuilt per tenant or recall silently falls — and "silently" is
+ * the disqualifying part. HNSW's recall is stable as rows are added, which is worth its build cost here.
+ *
+ * `m = 16, ef_construction = 64` are pgvector's defaults and the operating point its own benchmarks report as
+ * ~0.98 recall@10 on 1536-dimension embeddings. That figure is the recorded target; the measured figure for
+ * this platform's own query set is in the tests, against the exact in-memory index.
+ */
+export declare const VECTOR_MIGRATIONS: readonly Migration[];
+/** Whether this database can hold vectors, so a caller does not have to learn it from a failure. */
+export declare const hasVectorExtension: (sql: SqlExecutor) => Promise<boolean>;
+/** Applies the vector migrations. Call only where `hasVectorExtension` is true. */
+export declare const migrateVector: (sql: SqlExecutor) => Promise<void>;
+export declare const rollbackVector: (sql: SqlExecutor) => Promise<void>;
+/**
+ * The applied-migrations ledger. Defined here rather than in `schema.ts` because both provisioning
+ * paths write it -- `migrate()` below and `SchemaManager.apply()` -- and a second copy of the DDL is
+ * how they would drift. They did drift: `migrate()` used to apply statements without recording them,
+ * so `/readyz`'s schema probe read an empty ledger and never reported ready for anyone who
+ * provisioned with `migrate()` rather than `apply()`.
+ */
+export declare const MIGRATION_LEDGER = "CREATE TABLE IF NOT EXISTS schema_migrations (\n  id text PRIMARY KEY,\n  applied_at timestamptz NOT NULL DEFAULT now()\n)";
+/**
+ * Ledger rows, or an empty set where the table does not exist yet. Read-only: asking what has been
+ * applied must not itself apply anything.
+ */
+export declare const appliedMigrationIds: (sql: SqlExecutor) => Promise<Set<string>>;
+/**
+ * Applies every pending migration and records it.
+ *
+ * Migrations already in the ledger are skipped, but a schema provisioned before the ledger existed
+ * has the tables and no rows -- so the first run after upgrading re-executes all of them. That is
+ * safe because every statement is idempotent (`migrations-rerunnable.test.ts` is what keeps it so),
+ * and it leaves the ledger complete afterwards.
+ */
+export declare const migrate: (sql: SqlExecutor) => Promise<void>;
+export declare const rollback: (sql: SqlExecutor) => Promise<void>;
+//# sourceMappingURL=migrations.d.ts.map