@hexis-ai/engram-server 0.1.5 → 0.1.6

package/dist/adapters/postgres-key-store.d.ts

@@ -3,7 +3,10 @@ import type { SqlClient } from "./postgres";
 export declare class PostgresKeyStore implements KeyStore {
     private readonly sql;
     constructor(sql: SqlClient);
-    /** Create the key-store schema. Call once at boot. */
+    /**
+     * Apply all pending schema migrations. Safe to call repeatedly and
+     * concurrently with other instances — see `runMigrations` for details.
+     */
     ensureSchema(): Promise<void>;
     createWorkspace(input: {
         id?: string;

package/dist/adapters/postgres-key-store.js

@@ -1,34 +1,16 @@
 import { generateRawKey, hashKey, isValidWorkspaceId, keyPrefix, } from "../key-store";
-const KEY_STORE_SCHEMA_SQL = `
-CREATE TABLE IF NOT EXISTS engram_workspaces (
-  id          TEXT PRIMARY KEY,
-  name        TEXT,
-  metadata    JSONB NOT NULL DEFAULT '{}',
-  created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW()
-);
-
-CREATE TABLE IF NOT EXISTS engram_api_keys (
-  id            TEXT PRIMARY KEY,
-  workspace_id  TEXT NOT NULL REFERENCES engram_workspaces(id) ON DELETE CASCADE,
-  key_hash      TEXT NOT NULL UNIQUE,
-  prefix        TEXT NOT NULL,
-  name          TEXT,
-  created_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-  last_used_at  TIMESTAMPTZ,
-  revoked_at    TIMESTAMPTZ
-);
-
-CREATE INDEX IF NOT EXISTS idx_engram_api_keys_workspace
-  ON engram_api_keys (workspace_id);
-`;
+import { runMigrations } from "../migrator";
 export class PostgresKeyStore {
     sql;
     constructor(sql) {
         this.sql = sql;
     }
-    /** Create the key-store schema. Call once at boot. */
+    /**
+     * Apply all pending schema migrations. Safe to call repeatedly and
+     * concurrently with other instances — see `runMigrations` for details.
+     */
     async ensureSchema() {
-        await this.sql.unsafe(KEY_STORE_SCHEMA_SQL);
+        await runMigrations(this.sql);
     }
     async createWorkspace(input) {
         const id = input.id ?? crypto.randomUUID();

package/dist/adapters/postgres.d.ts

@@ -27,8 +27,8 @@ export declare class PostgresAdapter implements StorageAdapter {
     private readonly newPersonId;
     constructor(opts: PostgresAdapterOptions);
     /**
-     * Create the schema. Call once at boot. Safe to invoke repeatedly.
-     * Uses `sql.unsafe()` to ship the multi-statement DDL as a single batch.
+     * Apply all pending schema migrations. Safe to call repeatedly and
+     * concurrently with other instances — see `runMigrations` for details.
      */
     ensureSchema(): Promise<void>;
     createSession(init: SessionInit & {

package/dist/adapters/postgres.js

@@ -1,53 +1,5 @@
+import { runMigrations } from "../migrator";
 import { foldEvents } from "../storage";
-const SCHEMA_SQL = `
-CREATE TABLE IF NOT EXISTS engram_sessions (
-  workspace_id  TEXT      NOT NULL,
-  id            TEXT      NOT NULL,
-  title         TEXT,
-  channel       TEXT,
-  participants  TEXT[]    NOT NULL DEFAULT '{}',
-  viewable_by   TEXT[]    NOT NULL DEFAULT '{}',
-  created_at    TIMESTAMPTZ NOT NULL,
-  PRIMARY KEY (workspace_id, id)
-);
-
--- Existing deployments may pre-date viewable_by; backfill the column on
--- upgrade. Idempotent.
-ALTER TABLE engram_sessions ADD COLUMN IF NOT EXISTS viewable_by TEXT[] NOT NULL DEFAULT '{}';
-
-CREATE TABLE IF NOT EXISTS engram_events (
-  workspace_id TEXT NOT NULL,
-  session_id   TEXT NOT NULL,
-  seq          INTEGER NOT NULL,
-  type         TEXT NOT NULL,
-  at           TIMESTAMPTZ NOT NULL,
-  payload      JSONB NOT NULL,
-  PRIMARY KEY (workspace_id, session_id, seq),
-  FOREIGN KEY (workspace_id, session_id)
-    REFERENCES engram_sessions(workspace_id, id) ON DELETE CASCADE
-);
-
-CREATE TABLE IF NOT EXISTS engram_persons (
-  workspace_id  TEXT NOT NULL,
-  id            TEXT NOT NULL,
-  display_name  TEXT,
-  created_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
-  updated_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
-  PRIMARY KEY (workspace_id, id)
-);
-
-CREATE INDEX IF NOT EXISTS idx_engram_sessions_workspace_created
-  ON engram_sessions (workspace_id, created_at DESC);
-
--- Person-axis lookups. GIN supports the @> contains operator efficiently.
-CREATE INDEX IF NOT EXISTS idx_engram_sessions_participants
-  ON engram_sessions USING GIN (participants);
-CREATE INDEX IF NOT EXISTS idx_engram_sessions_viewable_by
-  ON engram_sessions USING GIN (viewable_by);
-
-CREATE INDEX IF NOT EXISTS idx_engram_persons_updated
-  ON engram_persons (workspace_id, updated_at DESC);
-`;
 /**
  * 10-char alphanumeric id, e.g. `p_a8b3c2d4`. Cryptographic randomness via
  * the platform's getRandomValues; collision probability negligible for any
@@ -72,11 +24,11 @@ export class PostgresAdapter {
         this.newPersonId = opts.newPersonId ?? defaultPersonId;
     }
     /**
-     * Create the schema. Call once at boot. Safe to invoke repeatedly.
-     * Uses `sql.unsafe()` to ship the multi-statement DDL as a single batch.
+     * Apply all pending schema migrations. Safe to call repeatedly and
+     * concurrently with other instances — see `runMigrations` for details.
      */
     async ensureSchema() {
-        await this.sql.unsafe(SCHEMA_SQL);
+        await runMigrations(this.sql);
     }
     // --- Sessions -----------------------------------------------------
     async createSession(init) {

package/dist/main.js

@@ -11,13 +11,10 @@
  *   DATABASE_URL               if unset, falls back to InMemoryKeyStore +
  *                              InMemoryAdapter (NOT durable across restarts)
  *   DATABASE_SOCKET_PATH       Cloud SQL Auth Proxy unix socket dir
- *   ENGRAM_API_KEY             legacy single-tenant key. When set, a workspace
- *                              identified by ENGRAM_WORKSPACE_ID is created on
- *                              boot and this raw key is registered against it,
- *                              keeping existing single-tenant deploys working
- *                              while the multi-tenant flow rolls out.
- *   ENGRAM_WORKSPACE_ID        default "default" — the workspace id used for
- *                              the legacy bootstrap above.
+ *
+ * Workspaces and their API keys are provisioned exclusively through the
+ * admin API. There is no single-tenant fallback — every caller must hold a
+ * workspace-scoped key issued by `POST /admin/v1/workspaces`.
  */
 import { createServer } from "./server";
 import { InMemoryAdapter } from "./adapters/memory";
@@ -26,8 +23,6 @@ import { InMemoryKeyStore } from "./adapters/memory-key-store";
 import { PostgresKeyStore } from "./adapters/postgres-key-store";
 const PORT = Number(process.env.PORT ?? 8080);
 const ADMIN_TOKEN = process.env.ENGRAM_ADMIN_TOKEN;
-const LEGACY_API_KEY = process.env.ENGRAM_API_KEY;
-const LEGACY_WORKSPACE_ID = process.env.ENGRAM_WORKSPACE_ID ?? "default";
 const DATABASE_URL = process.env.DATABASE_URL;
 const DATABASE_SOCKET_PATH = process.env.DATABASE_SOCKET_PATH;
 if (!ADMIN_TOKEN) {
@@ -35,11 +30,6 @@ if (!ADMIN_TOKEN) {
     process.exit(1);
 }
 const { keyStore, getStorage } = await buildStores();
-if (LEGACY_API_KEY) {
-    await keyStore.createWorkspace({ id: LEGACY_WORKSPACE_ID, name: "Legacy" });
-    await keyStore.registerLegacyKey(LEGACY_WORKSPACE_ID, LEGACY_API_KEY, "ENGRAM_API_KEY");
-    console.log(`[engram-server] legacy key bootstrapped (workspace=${LEGACY_WORKSPACE_ID})`);
-}
 const app = createServer({
     auth: async (key) => {
         const r = await keyStore.resolveKey(key);

package/dist/migrations/0001-baseline.d.ts

@@ -0,0 +1,2 @@
+export declare const name = "0001-baseline";
+export declare const sql = "\n-- Session storage (workspace-scoped).\nCREATE TABLE IF NOT EXISTS engram_sessions (\n  workspace_id  TEXT      NOT NULL,\n  id            TEXT      NOT NULL,\n  title         TEXT,\n  channel       TEXT,\n  participants  TEXT[]    NOT NULL DEFAULT '{}',\n  viewable_by   TEXT[]    NOT NULL DEFAULT '{}',\n  created_at    TIMESTAMPTZ NOT NULL,\n  PRIMARY KEY (workspace_id, id)\n);\n\n-- Deployments that pre-date viewable_by need the column backfilled.\nALTER TABLE engram_sessions ADD COLUMN IF NOT EXISTS viewable_by TEXT[] NOT NULL DEFAULT '{}';\n\nCREATE TABLE IF NOT EXISTS engram_events (\n  workspace_id TEXT NOT NULL,\n  session_id   TEXT NOT NULL,\n  seq          INTEGER NOT NULL,\n  type         TEXT NOT NULL,\n  at           TIMESTAMPTZ NOT NULL,\n  payload      JSONB NOT NULL,\n  PRIMARY KEY (workspace_id, session_id, seq),\n  FOREIGN KEY (workspace_id, session_id)\n    REFERENCES engram_sessions(workspace_id, id) ON DELETE CASCADE\n);\n\nCREATE TABLE IF NOT EXISTS engram_persons (\n  workspace_id  TEXT NOT NULL,\n  id            TEXT NOT NULL,\n  display_name  TEXT,\n  created_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n  updated_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n  PRIMARY KEY (workspace_id, id)\n);\n\nCREATE INDEX IF NOT EXISTS idx_engram_sessions_workspace_created\n  ON engram_sessions (workspace_id, created_at DESC);\n\n-- Person-axis lookups. GIN supports the @> contains operator efficiently.\nCREATE INDEX IF NOT EXISTS idx_engram_sessions_participants\n  ON engram_sessions USING GIN (participants);\nCREATE INDEX IF NOT EXISTS idx_engram_sessions_viewable_by\n  ON engram_sessions USING GIN (viewable_by);\n\nCREATE INDEX IF NOT EXISTS idx_engram_persons_updated\n  ON engram_persons (workspace_id, updated_at DESC);\n\n-- Control plane: workspaces + API keys.\nCREATE TABLE IF NOT EXISTS engram_workspaces (\n  id          TEXT PRIMARY KEY,\n  name        TEXT,\n  metadata    JSONB NOT NULL DEFAULT '{}',\n  created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW()\n);\n\nCREATE TABLE IF NOT EXISTS engram_api_keys (\n  id            TEXT PRIMARY KEY,\n  workspace_id  TEXT NOT NULL REFERENCES engram_workspaces(id) ON DELETE CASCADE,\n  key_hash      TEXT NOT NULL UNIQUE,\n  prefix        TEXT NOT NULL,\n  name          TEXT,\n  created_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n  last_used_at  TIMESTAMPTZ,\n  revoked_at    TIMESTAMPTZ\n);\n\nCREATE INDEX IF NOT EXISTS idx_engram_api_keys_workspace\n  ON engram_api_keys (workspace_id);\n";

package/dist/migrations/0001-baseline.js

@@ -0,0 +1,72 @@
+export const name = "0001-baseline";
+export const sql = `
+-- Session storage (workspace-scoped).
+CREATE TABLE IF NOT EXISTS engram_sessions (
+  workspace_id  TEXT      NOT NULL,
+  id            TEXT      NOT NULL,
+  title         TEXT,
+  channel       TEXT,
+  participants  TEXT[]    NOT NULL DEFAULT '{}',
+  viewable_by   TEXT[]    NOT NULL DEFAULT '{}',
+  created_at    TIMESTAMPTZ NOT NULL,
+  PRIMARY KEY (workspace_id, id)
+);
+
+-- Deployments that pre-date viewable_by need the column backfilled.
+ALTER TABLE engram_sessions ADD COLUMN IF NOT EXISTS viewable_by TEXT[] NOT NULL DEFAULT '{}';
+
+CREATE TABLE IF NOT EXISTS engram_events (
+  workspace_id TEXT NOT NULL,
+  session_id   TEXT NOT NULL,
+  seq          INTEGER NOT NULL,
+  type         TEXT NOT NULL,
+  at           TIMESTAMPTZ NOT NULL,
+  payload      JSONB NOT NULL,
+  PRIMARY KEY (workspace_id, session_id, seq),
+  FOREIGN KEY (workspace_id, session_id)
+    REFERENCES engram_sessions(workspace_id, id) ON DELETE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS engram_persons (
+  workspace_id  TEXT NOT NULL,
+  id            TEXT NOT NULL,
+  display_name  TEXT,
+  created_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  PRIMARY KEY (workspace_id, id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_engram_sessions_workspace_created
+  ON engram_sessions (workspace_id, created_at DESC);
+
+-- Person-axis lookups. GIN supports the @> contains operator efficiently.
+CREATE INDEX IF NOT EXISTS idx_engram_sessions_participants
+  ON engram_sessions USING GIN (participants);
+CREATE INDEX IF NOT EXISTS idx_engram_sessions_viewable_by
+  ON engram_sessions USING GIN (viewable_by);
+
+CREATE INDEX IF NOT EXISTS idx_engram_persons_updated
+  ON engram_persons (workspace_id, updated_at DESC);
+
+-- Control plane: workspaces + API keys.
+CREATE TABLE IF NOT EXISTS engram_workspaces (
+  id          TEXT PRIMARY KEY,
+  name        TEXT,
+  metadata    JSONB NOT NULL DEFAULT '{}',
+  created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE TABLE IF NOT EXISTS engram_api_keys (
+  id            TEXT PRIMARY KEY,
+  workspace_id  TEXT NOT NULL REFERENCES engram_workspaces(id) ON DELETE CASCADE,
+  key_hash      TEXT NOT NULL UNIQUE,
+  prefix        TEXT NOT NULL,
+  name          TEXT,
+  created_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  last_used_at  TIMESTAMPTZ,
+  revoked_at    TIMESTAMPTZ
+);
+
+CREATE INDEX IF NOT EXISTS idx_engram_api_keys_workspace
+  ON engram_api_keys (workspace_id);
+`;

package/dist/migrations/index.d.ts

@@ -0,0 +1,12 @@
+export interface Migration {
+    name: string;
+    sql: string;
+}
+/**
+ * Schema migrations, applied in array order. Add a new file under
+ * `migrations/NNNN-<slug>.ts` exporting `name` and `sql`, then append it
+ * here. Each migration's SQL must be idempotent (CREATE TABLE IF NOT
+ * EXISTS, ADD COLUMN IF NOT EXISTS, etc.) so a first apply on a DB that
+ * predates the migrator is a no-op.
+ */
+export declare const MIGRATIONS: Migration[];

package/dist/migrations/index.js

@@ -0,0 +1,9 @@
+import * as m0001 from "./0001-baseline";
+/**
+ * Schema migrations, applied in array order. Add a new file under
+ * `migrations/NNNN-<slug>.ts` exporting `name` and `sql`, then append it
+ * here. Each migration's SQL must be idempotent (CREATE TABLE IF NOT
+ * EXISTS, ADD COLUMN IF NOT EXISTS, etc.) so a first apply on a DB that
+ * predates the migrator is a no-op.
+ */
+export const MIGRATIONS = [{ name: m0001.name, sql: m0001.sql }];

package/dist/migrator.d.ts

@@ -0,0 +1,17 @@
+import type { SqlClient } from "./adapters/postgres";
+import { type Migration } from "./migrations";
+/**
+ * Apply pending schema migrations in order. Records applied migrations in
+ * `engram_schema_migrations` so subsequent boots skip them.
+ *
+ * Each migration's SQL must itself be idempotent (IF NOT EXISTS, etc.) —
+ * the tracking table protects against unnecessary re-runs but a partial
+ * failure between executing the SQL and inserting the tracking row would
+ * cause a replay on next boot, and we want that replay to be a no-op.
+ *
+ * Safe to call concurrently from multiple instances: the INSERT uses ON
+ * CONFLICT and the migration SQL itself is idempotent, so two boots
+ * applying the same migration in parallel just race to a consistent end
+ * state.
+ */
+export declare function runMigrations(sql: SqlClient, migrations?: readonly Migration[]): Promise<void>;

package/dist/migrator.js

@@ -0,0 +1,37 @@
+import { MIGRATIONS } from "./migrations";
+/**
+ * Apply pending schema migrations in order. Records applied migrations in
+ * `engram_schema_migrations` so subsequent boots skip them.
+ *
+ * Each migration's SQL must itself be idempotent (IF NOT EXISTS, etc.) —
+ * the tracking table protects against unnecessary re-runs but a partial
+ * failure between executing the SQL and inserting the tracking row would
+ * cause a replay on next boot, and we want that replay to be a no-op.
+ *
+ * Safe to call concurrently from multiple instances: the INSERT uses ON
+ * CONFLICT and the migration SQL itself is idempotent, so two boots
+ * applying the same migration in parallel just race to a consistent end
+ * state.
+ */
+export async function runMigrations(sql, migrations = MIGRATIONS) {
+    await sql.unsafe(`
+    CREATE TABLE IF NOT EXISTS engram_schema_migrations (
+      name       TEXT PRIMARY KEY,
+      applied_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+    )
+  `);
+    const appliedRows = await sql `
+    SELECT name FROM engram_schema_migrations
+  `;
+    const applied = new Set(appliedRows.map((r) => r.name));
+    for (const m of migrations) {
+        if (applied.has(m.name))
+            continue;
+        await sql.unsafe(m.sql);
+        await sql `
+      INSERT INTO engram_schema_migrations (name)
+      VALUES (${m.name})
+      ON CONFLICT (name) DO NOTHING
+    `;
+    }
+}

package/package.json

@@ -1,8 +1,15 @@
 {
   "name": "@hexis-ai/engram-server",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Engram server: ingest agent session events, persist via a pluggable adapter, expose search.",
-  "keywords": ["engram", "agents", "search", "hono", "postgres", "server"],
+  "keywords": [
+    "engram",
+    "agents",
+    "search",
+    "hono",
+    "postgres",
+    "server"
+  ],
   "homepage": "https://github.com/hexis-ltd/engram#readme",
   "repository": {
     "type": "git",
@@ -49,7 +56,9 @@
     "postgres": "^3.4.0"
   },
   "peerDependenciesMeta": {
-    "postgres": { "optional": true }
+    "postgres": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "postgres": "^3.4.0"