@hexis-ai/engram-server 0.3.0 → 0.5.0

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

@@ -1,4 +1,4 @@
-import { generateRawKey, hashKey, isValidWorkspaceId, keyPrefix, } from "../key-store";
+import { deriveKey, hashKey, mintKey, resolveWorkspaceId, } from "../key-store";
 /**
  * In-process KeyStore for tests and single-node dev. Volatile.
  */
@@ -7,9 +7,7 @@ export class InMemoryKeyStore {
     keys = new Map();
     byHash = new Map();
     async createWorkspace(input) {
-        const id = input.id ?? crypto.randomUUID();
-        if (!isValidWorkspaceId(id))
-            throw new Error("invalid_workspace_id");
+        const id = resolveWorkspaceId(input);
         const existing = this.workspaces.get(id);
         if (existing)
             return existing;
@@ -40,12 +38,12 @@ export class InMemoryKeyStore {
     async issueKey(workspaceId, opts = {}) {
         if (!this.workspaces.has(workspaceId))
             throw new Error("workspace_not_found");
-        const raw = generateRawKey();
+        const { id, hash, prefix, raw } = mintKey();
         const row = {
-            id: crypto.randomUUID(),
+            id,
             workspaceId,
-            keyHash: hashKey(raw),
-            prefix: keyPrefix(raw),
+            keyHash: hash,
+            prefix,
             ...(opts.name !== undefined ? { name: opts.name } : {}),
             createdAt: new Date().toISOString(),
         };
@@ -80,14 +78,14 @@ export class InMemoryKeyStore {
     async registerKey(workspaceId, rawKey, name) {
         if (!this.workspaces.has(workspaceId))
             throw new Error("workspace_not_found");
-        const hash = hashKey(rawKey);
+        const { id, hash, prefix } = deriveKey(rawKey);
         if (this.byHash.has(hash))
             return;
         const row = {
-            id: crypto.randomUUID(),
+            id,
             workspaceId,
             keyHash: hash,
-            prefix: keyPrefix(rawKey),
+            prefix,
             ...(name !== undefined ? { name } : {}),
             createdAt: new Date().toISOString(),
         };

package/dist/adapters/memory.d.ts

@@ -1,5 +1,5 @@
 import type { Session } from "@hexis-ai/engram-core";
-import type { PersonCreate, PersonInfo, PersonUpdate, SessionEvent, SessionInit } from "@hexis-ai/engram-sdk";
+import type { AliasInfo, AliasUpsert, PersonCreate, PersonInfo, PersonUpdate, SessionEvent, SessionInit } from "@hexis-ai/engram-sdk";
 import { type StorageAdapter } from "../storage";
 export interface InMemoryAdapterOptions {
     /** Override for tests. Default: `p_${random}` with 8 chars. */
@@ -12,6 +12,8 @@ export interface InMemoryAdapterOptions {
 export declare class InMemoryAdapter implements StorageAdapter {
     private readonly sessions;
     private readonly persons;
+    /** Keyed by `${personId} ${name.toLowerCase()}` — see `aliasKey` below. */
+    private readonly aliases;
     private readonly newPersonId;
     constructor(opts?: InMemoryAdapterOptions);
     createSession(init: SessionInit & {
@@ -20,6 +22,7 @@ export declare class InMemoryAdapter implements StorageAdapter {
     }): Promise<void>;
     appendEvents(sessionId: string, events: SessionEvent[]): Promise<void>;
     getSession(sessionId: string): Promise<Session | null>;
+    getSessionEvents(sessionId: string): Promise<SessionEvent[] | null>;
     listSessions(opts: {
         limit: number;
         channel?: string;
@@ -38,4 +41,8 @@ export declare class InMemoryAdapter implements StorageAdapter {
         limit: number;
         q?: string;
     }): Promise<PersonInfo[]>;
+    upsertAlias(personId: string, input: {
+        name: string;
+    } & AliasUpsert): Promise<AliasInfo | null>;
+    listAliases(personId: string): Promise<AliasInfo[]>;
 }

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

@@ -1,4 +1,4 @@
-import { generateRawKey, hashKey, isValidWorkspaceId, keyPrefix, } from "../key-store";
+import { deriveKey, hashKey, mintKey, resolveWorkspaceId, } from "../key-store";
 import { runMigrations } from "../migrator";
 export class PostgresKeyStore {
     sql;
@@ -13,9 +13,7 @@ export class PostgresKeyStore {
         await runMigrations(this.sql);
     }
     async createWorkspace(input) {
-        const id = input.id ?? crypto.randomUUID();
-        if (!isValidWorkspaceId(id))
-            throw new Error("invalid_workspace_id");
+        const id = resolveWorkspaceId(input);
         await this.sql `
       INSERT INTO engram_workspaces (id, name, metadata)
       VALUES (${id}, ${input.name ?? null}, ${(input.metadata ?? {})})
@@ -49,10 +47,7 @@ export class PostgresKeyStore {
         const ws = await this.getWorkspace(workspaceId);
         if (!ws)
             throw new Error("workspace_not_found");
-        const raw = generateRawKey();
-        const id = crypto.randomUUID();
-        const hash = hashKey(raw);
-        const prefix = keyPrefix(raw);
+        const { id, hash, prefix, raw } = mintKey();
         const rows = await this.sql `
       INSERT INTO engram_api_keys (id, workspace_id, key_hash, prefix, name)
       VALUES (${id}, ${workspaceId}, ${hash}, ${prefix}, ${opts.name ?? null})
@@ -110,11 +105,10 @@ export class PostgresKeyStore {
         const ws = await this.getWorkspace(workspaceId);
         if (!ws)
             throw new Error("workspace_not_found");
-        const hash = hashKey(rawKey);
-        const id = crypto.randomUUID();
+        const { id, hash, prefix } = deriveKey(rawKey);
         await this.sql `
       INSERT INTO engram_api_keys (id, workspace_id, key_hash, prefix, name)
-      VALUES (${id}, ${workspaceId}, ${hash}, ${keyPrefix(rawKey)}, ${name ?? null})
+      VALUES (${id}, ${workspaceId}, ${hash}, ${prefix}, ${name ?? null})
       ON CONFLICT (key_hash) DO NOTHING
     `;
     }

package/dist/adapters/postgres.d.ts

@@ -1,5 +1,5 @@
 import type { Session } from "@hexis-ai/engram-core";
-import type { PersonCreate, PersonInfo, PersonUpdate, SessionEvent, SessionInit } from "@hexis-ai/engram-sdk";
+import type { AliasInfo, AliasUpsert, PersonCreate, PersonInfo, PersonUpdate, SessionEvent, SessionInit } from "@hexis-ai/engram-sdk";
 import { type StorageAdapter } from "../storage";
 /**
  * Minimal subset of `postgres` driver's tagged-template surface that this
@@ -37,6 +37,7 @@ export declare class PostgresAdapter implements StorageAdapter {
     }): Promise<void>;
     appendEvents(sessionId: string, events: SessionEvent[]): Promise<void>;
     getSession(sessionId: string): Promise<Session | null>;
+    getSessionEvents(sessionId: string): Promise<SessionEvent[] | null>;
     listSessions(opts: {
         limit: number;
         channel?: string;
@@ -55,4 +56,8 @@ export declare class PostgresAdapter implements StorageAdapter {
         limit: number;
         q?: string;
     }): Promise<PersonInfo[]>;
+    upsertAlias(personId: string, input: {
+        name: string;
+    } & AliasUpsert): Promise<AliasInfo | null>;
+    listAliases(personId: string): Promise<AliasInfo[]>;
 }

package/dist/adapters/postgres.js

@@ -110,6 +110,21 @@ export class PostgresAdapter {
         };
         return foldEvents(row, events.map((e) => e.payload), new Date());
     }
+    async getSessionEvents(sessionId) {
+        const rows = await this.sql `
+      SELECT id FROM engram_sessions
+      WHERE workspace_id = ${this.workspaceId} AND id = ${sessionId}
+      LIMIT 1
+    `;
+        if (rows.length === 0)
+            return null;
+        const events = await this.sql `
+      SELECT payload FROM engram_events
+      WHERE workspace_id = ${this.workspaceId} AND session_id = ${sessionId}
+      ORDER BY seq
+    `;
+        return events.map((e) => e.payload);
+    }
     async listSessions(opts) {
         const channelFilter = opts.channel ?? null;
         const rows = await this.sql `
@@ -222,6 +237,57 @@ export class PostgresAdapter {
     `;
         return rows.map(toPersonInfo);
     }
+    // --- Aliases ------------------------------------------------------
+    async upsertAlias(personId, input) {
+        // Pre-check rather than rely on the FK so unknown persons return
+        // `null` instead of throwing a constraint violation.
+        const personExists = await this.sql `
+      SELECT id FROM engram_persons
+      WHERE workspace_id = ${this.workspaceId} AND id = ${personId}
+      LIMIT 1
+    `;
+        if (personExists.length === 0)
+            return null;
+        const increment = input.increment ?? true;
+        // Branch on the upsert behaviour. `increment=true` bumps usage_count
+        // and replaces caller/last_used; `increment=false` is idempotent —
+        // a no-op when the row already exists.
+        const rows = increment
+            ? await this.sql `
+          INSERT INTO engram_aliases (workspace_id, person_id, name, caller, usage_count, last_used)
+          VALUES (
+            ${this.workspaceId}, ${personId}, ${input.name},
+            ${input.caller}, 1, ${input.last_used}
+          )
+          ON CONFLICT (workspace_id, person_id, name_lower) DO UPDATE SET
+            usage_count = engram_aliases.usage_count + 1,
+            caller      = EXCLUDED.caller,
+            last_used   = EXCLUDED.last_used,
+            updated_at  = now()
+          RETURNING person_id, name, caller, usage_count, last_used, created_at, updated_at
+        `
+            : await this.sql `
+          INSERT INTO engram_aliases (workspace_id, person_id, name, caller, usage_count, last_used)
+          VALUES (
+            ${this.workspaceId}, ${personId}, ${input.name},
+            ${input.caller}, 1, ${input.last_used}
+          )
+          ON CONFLICT (workspace_id, person_id, name_lower) DO UPDATE SET
+            -- No-op update so RETURNING still produces a row.
+            updated_at = engram_aliases.updated_at
+          RETURNING person_id, name, caller, usage_count, last_used, created_at, updated_at
+        `;
+        return toAliasInfo(rows[0]);
+    }
+    async listAliases(personId) {
+        const rows = await this.sql `
+      SELECT person_id, name, caller, usage_count, last_used, created_at, updated_at
+      FROM engram_aliases
+      WHERE workspace_id = ${this.workspaceId} AND person_id = ${personId}
+      ORDER BY last_used DESC
+    `;
+        return rows.map(toAliasInfo);
+    }
 }
 function toPersonInfo(r) {
     const toIso = (v) => (typeof v === "string" ? v : v.toISOString());
@@ -232,3 +298,20 @@ function toPersonInfo(r) {
         updated_at: toIso(r.updated_at),
     };
 }
+function toAliasInfo(r) {
+    const toIso = (v) => (typeof v === "string" ? v : v.toISOString());
+    // last_used is a DATE column; postgres-js returns it as a Date at UTC
+    // midnight. Render as plain YYYY-MM-DD to match the wire type.
+    const lastUsed = typeof r.last_used === "string"
+        ? r.last_used.slice(0, 10)
+        : r.last_used.toISOString().slice(0, 10);
+    return {
+        person_id: r.person_id,
+        name: r.name,
+        caller: r.caller,
+        usage_count: r.usage_count,
+        last_used: lastUsed,
+        created_at: toIso(r.created_at),
+        updated_at: toIso(r.updated_at),
+    };
+}

package/dist/key-store.d.ts

@@ -61,3 +61,32 @@ export declare function generateRawKey(): string;
 export declare function hashKey(raw: string): string;
 export declare function keyPrefix(raw: string): string;
 export declare function isValidWorkspaceId(id: string): boolean;
+/**
+ * Resolve the workspace id for a `createWorkspace` call: fall back to a random
+ * UUID when none is supplied, then validate. Shared by every KeyStore so the
+ * id policy can't drift between the in-memory and Postgres adapters.
+ */
+export declare function resolveWorkspaceId(input: {
+    id?: string;
+}): string;
+/** Derived material for a single API key row. */
+export interface KeyMaterial {
+    /** Row id (primary key). */
+    id: string;
+    /** SHA-256 hash of the raw key — the only form that gets persisted. */
+    hash: string;
+    /** Human-readable prefix shown in listings. */
+    prefix: string;
+}
+/**
+ * Mint a brand-new random key. Returns the persistable material plus the
+ * plaintext `raw` key, which the caller must return to the user exactly once.
+ */
+export declare function mintKey(): KeyMaterial & {
+    raw: string;
+};
+/**
+ * Derive persistable material for a caller-supplied raw key (`registerKey`).
+ * Unlike `mintKey`, the raw key already exists and is not returned.
+ */
+export declare function deriveKey(raw: string): KeyMaterial;

package/dist/key-store.js

@@ -15,3 +15,29 @@ export function keyPrefix(raw) {
 export function isValidWorkspaceId(id) {
     return WORKSPACE_ID_RE.test(id);
 }
+/**
+ * Resolve the workspace id for a `createWorkspace` call: fall back to a random
+ * UUID when none is supplied, then validate. Shared by every KeyStore so the
+ * id policy can't drift between the in-memory and Postgres adapters.
+ */
+export function resolveWorkspaceId(input) {
+    const id = input.id ?? crypto.randomUUID();
+    if (!isValidWorkspaceId(id))
+        throw new Error("invalid_workspace_id");
+    return id;
+}
+/**
+ * Mint a brand-new random key. Returns the persistable material plus the
+ * plaintext `raw` key, which the caller must return to the user exactly once.
+ */
+export function mintKey() {
+    const raw = generateRawKey();
+    return { id: crypto.randomUUID(), hash: hashKey(raw), prefix: keyPrefix(raw), raw };
+}
+/**
+ * Derive persistable material for a caller-supplied raw key (`registerKey`).
+ * Unlike `mintKey`, the raw key already exists and is not returned.
+ */
+export function deriveKey(raw) {
+    return { id: crypto.randomUUID(), hash: hashKey(raw), prefix: keyPrefix(raw) };
+}

package/dist/migrations/0002-aliases.d.ts

@@ -0,0 +1,2 @@
+export declare const name = "0002-aliases";
+export declare const sql = "\n-- Per-person alias history. Mirrors monet's `aliases` table at the\n-- canonical-engram level so identity resolution can move out of monet\n-- once consumers catch up. Keyed by name_lower (case-insensitive,\n-- DB-generated) so case variants collapse.\nCREATE TABLE IF NOT EXISTS engram_aliases (\n  workspace_id  TEXT NOT NULL,\n  person_id     TEXT NOT NULL,\n  name          TEXT NOT NULL,\n  name_lower    TEXT GENERATED ALWAYS AS (lower(name)) STORED,\n  caller        TEXT NOT NULL,\n  usage_count   INTEGER NOT NULL DEFAULT 1,\n  last_used     DATE NOT NULL,\n  created_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n  updated_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n  PRIMARY KEY (workspace_id, person_id, name_lower),\n  FOREIGN KEY (workspace_id, person_id)\n    REFERENCES engram_persons(workspace_id, id) ON DELETE CASCADE\n);\n\n-- Reverse lookup: \"who answers to this name?\" is the common identity-\n-- resolution query and benefits from an index on the lowercased form.\nCREATE INDEX IF NOT EXISTS idx_engram_aliases_name_lower\n  ON engram_aliases (workspace_id, name_lower);\n\n-- Forward lookup: list all of a person's aliases by recency.\nCREATE INDEX IF NOT EXISTS idx_engram_aliases_person_last_used\n  ON engram_aliases (workspace_id, person_id, last_used DESC);\n";

package/dist/migrations/0002-aliases.js

@@ -0,0 +1,30 @@
+export const name = "0002-aliases";
+export const sql = `
+-- Per-person alias history. Mirrors monet's \`aliases\` table at the
+-- canonical-engram level so identity resolution can move out of monet
+-- once consumers catch up. Keyed by name_lower (case-insensitive,
+-- DB-generated) so case variants collapse.
+CREATE TABLE IF NOT EXISTS engram_aliases (
+  workspace_id  TEXT NOT NULL,
+  person_id     TEXT NOT NULL,
+  name          TEXT NOT NULL,
+  name_lower    TEXT GENERATED ALWAYS AS (lower(name)) STORED,
+  caller        TEXT NOT NULL,
+  usage_count   INTEGER NOT NULL DEFAULT 1,
+  last_used     DATE NOT NULL,
+  created_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  PRIMARY KEY (workspace_id, person_id, name_lower),
+  FOREIGN KEY (workspace_id, person_id)
+    REFERENCES engram_persons(workspace_id, id) ON DELETE CASCADE
+);
+
+-- Reverse lookup: \"who answers to this name?\" is the common identity-
+-- resolution query and benefits from an index on the lowercased form.
+CREATE INDEX IF NOT EXISTS idx_engram_aliases_name_lower
+  ON engram_aliases (workspace_id, name_lower);
+
+-- Forward lookup: list all of a person's aliases by recency.
+CREATE INDEX IF NOT EXISTS idx_engram_aliases_person_last_used
+  ON engram_aliases (workspace_id, person_id, last_used DESC);
+`;

package/dist/migrations/index.js

@@ -1,4 +1,5 @@
 import * as m0001 from "./0001-baseline";
+import * as m0002 from "./0002-aliases";
 /**
  * Schema migrations, applied in array order. Add a new file under
  * `migrations/NNNN-<slug>.ts` exporting `name` and `sql`, then append it
@@ -6,4 +7,7 @@ import * as m0001 from "./0001-baseline";
  * 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 }];
+export const MIGRATIONS = [
+    { name: m0001.name, sql: m0001.sql },
+    { name: m0002.name, sql: m0002.sql },
+];