@hexis-ai/engram-server 0.5.0 → 0.6.0

package/dist/adapters/memory.d.ts

@@ -1,5 +1,5 @@
 import type { Session } from "@hexis-ai/engram-core";
-import type { AliasInfo, AliasUpsert, PersonCreate, PersonInfo, PersonUpdate, SessionEvent, SessionInit } from "@hexis-ai/engram-sdk";
+import type { AliasInfo, AliasUpsert, IdentityInfo, IdentityUpsert, 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. */
@@ -14,6 +14,8 @@ export declare class InMemoryAdapter implements StorageAdapter {
     private readonly persons;
     /** Keyed by `${personId} ${name.toLowerCase()}` — see `aliasKey` below. */
     private readonly aliases;
+    /** Keyed by ref (e.g. `slack:U12345`). */
+    private readonly identities;
     private readonly newPersonId;
     constructor(opts?: InMemoryAdapterOptions);
     createSession(init: SessionInit & {
@@ -45,4 +47,7 @@ export declare class InMemoryAdapter implements StorageAdapter {
         name: string;
     } & AliasUpsert): Promise<AliasInfo | null>;
     listAliases(personId: string): Promise<AliasInfo[]>;
+    upsertIdentity(ref: string, input: IdentityUpsert): Promise<IdentityInfo | null>;
+    getIdentityByRef(ref: string): Promise<IdentityInfo | null>;
+    listIdentitiesByPerson(personId: string): Promise<IdentityInfo[]>;
 }

package/dist/adapters/postgres.d.ts

@@ -1,5 +1,5 @@
 import type { Session } from "@hexis-ai/engram-core";
-import type { AliasInfo, AliasUpsert, PersonCreate, PersonInfo, PersonUpdate, SessionEvent, SessionInit } from "@hexis-ai/engram-sdk";
+import type { AliasInfo, AliasUpsert, IdentityInfo, IdentityUpsert, 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
@@ -60,4 +60,7 @@ export declare class PostgresAdapter implements StorageAdapter {
         name: string;
     } & AliasUpsert): Promise<AliasInfo | null>;
     listAliases(personId: string): Promise<AliasInfo[]>;
+    upsertIdentity(ref: string, input: IdentityUpsert): Promise<IdentityInfo | null>;
+    getIdentityByRef(ref: string): Promise<IdentityInfo | null>;
+    listIdentitiesByPerson(personId: string): Promise<IdentityInfo[]>;
 }

package/dist/adapters/postgres.js

@@ -288,6 +288,66 @@ export class PostgresAdapter {
     `;
         return rows.map(toAliasInfo);
     }
+    // --- Identities ---------------------------------------------------
+    async upsertIdentity(ref, 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 = ${input.person_id}
+      LIMIT 1
+    `;
+        if (personExists.length === 0)
+            return null;
+        const rows = await this.sql `
+      INSERT INTO engram_identities (
+        workspace_id, ref, person_id, service, external_id,
+        display_name, source, is_primary, picture, linked_at
+      )
+      VALUES (
+        ${this.workspaceId}, ${ref}, ${input.person_id},
+        ${input.service}, ${input.external_id},
+        ${input.display_name ?? null}, ${input.source ?? null},
+        ${input.is_primary ?? null}, ${input.picture ?? null},
+        ${input.linked_at}
+      )
+      ON CONFLICT (workspace_id, ref) DO UPDATE SET
+        person_id    = EXCLUDED.person_id,
+        service      = EXCLUDED.service,
+        external_id  = EXCLUDED.external_id,
+        display_name = COALESCE(EXCLUDED.display_name, engram_identities.display_name),
+        source       = COALESCE(EXCLUDED.source,       engram_identities.source),
+        is_primary   = COALESCE(EXCLUDED.is_primary,   engram_identities.is_primary),
+        picture      = COALESCE(EXCLUDED.picture,      engram_identities.picture),
+        linked_at    = EXCLUDED.linked_at,
+        updated_at   = now()
+      RETURNING ref, person_id, service, external_id, display_name, source,
+                is_primary, picture, linked_at, created_at, updated_at
+    `;
+        return toIdentityInfo(rows[0]);
+    }
+    async getIdentityByRef(ref) {
+        const rows = await this.sql `
+      SELECT ref, person_id, service, external_id, display_name, source,
+             is_primary, picture, linked_at, created_at, updated_at
+      FROM engram_identities
+      WHERE workspace_id = ${this.workspaceId} AND ref = ${ref}
+      LIMIT 1
+    `;
+        if (rows.length === 0)
+            return null;
+        return toIdentityInfo(rows[0]);
+    }
+    async listIdentitiesByPerson(personId) {
+        const rows = await this.sql `
+      SELECT ref, person_id, service, external_id, display_name, source,
+             is_primary, picture, linked_at, created_at, updated_at
+      FROM engram_identities
+      WHERE workspace_id = ${this.workspaceId} AND person_id = ${personId}
+      ORDER BY linked_at DESC
+    `;
+        return rows.map(toIdentityInfo);
+    }
 }
 function toPersonInfo(r) {
     const toIso = (v) => (typeof v === "string" ? v : v.toISOString());
@@ -315,3 +375,22 @@ function toAliasInfo(r) {
         updated_at: toIso(r.updated_at),
     };
 }
+function toIdentityInfo(r) {
+    const toIso = (v) => (typeof v === "string" ? v : v.toISOString());
+    const linkedAt = typeof r.linked_at === "string"
+        ? r.linked_at.slice(0, 10)
+        : r.linked_at.toISOString().slice(0, 10);
+    return {
+        ref: r.ref,
+        person_id: r.person_id,
+        service: r.service,
+        external_id: r.external_id,
+        display_name: r.display_name,
+        source: r.source,
+        is_primary: r.is_primary,
+        picture: r.picture,
+        linked_at: linkedAt,
+        created_at: toIso(r.created_at),
+        updated_at: toIso(r.updated_at),
+    };
+}

package/dist/migrations/0003-identities.d.ts

@@ -0,0 +1,2 @@
+export declare const name = "0003-identities";
+export declare const sql = "\n-- External identity \u2192 person mapping. Mirrors monet's `identities`\n-- table at the canonical-engram level so identity resolution\n-- (slack:U12345 \u2192 person id, email:foo@bar \u2192 person id, \u2026) can move\n-- out of monet once consumers catch up.\n--\n-- Ref is workspace-scoped here even though monet's PK is just `ref`;\n-- engram is multi-tenant from the floor up.\nCREATE TABLE IF NOT EXISTS engram_identities (\n  workspace_id  TEXT NOT NULL,\n  ref           TEXT NOT NULL,\n  person_id     TEXT NOT NULL,\n  service       TEXT NOT NULL,\n  external_id   TEXT NOT NULL,\n  display_name  TEXT,\n  source        TEXT,\n  is_primary    BOOLEAN,\n  picture       TEXT,\n  linked_at     DATE NOT NULL,\n  created_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n  updated_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n  PRIMARY KEY (workspace_id, ref),\n  FOREIGN KEY (workspace_id, person_id)\n    REFERENCES engram_persons(workspace_id, id) ON DELETE CASCADE\n);\n\n-- The two query shapes the resolver needs.\nCREATE INDEX IF NOT EXISTS idx_engram_identities_person\n  ON engram_identities (workspace_id, person_id);\nCREATE INDEX IF NOT EXISTS idx_engram_identities_service_external\n  ON engram_identities (workspace_id, service, external_id);\n";

package/dist/migrations/0003-identities.js

@@ -0,0 +1,33 @@
+export const name = "0003-identities";
+export const sql = `
+-- External identity → person mapping. Mirrors monet's \`identities\`
+-- table at the canonical-engram level so identity resolution
+-- (slack:U12345 → person id, email:foo@bar → person id, …) can move
+-- out of monet once consumers catch up.
+--
+-- Ref is workspace-scoped here even though monet's PK is just \`ref\`;
+-- engram is multi-tenant from the floor up.
+CREATE TABLE IF NOT EXISTS engram_identities (
+  workspace_id  TEXT NOT NULL,
+  ref           TEXT NOT NULL,
+  person_id     TEXT NOT NULL,
+  service       TEXT NOT NULL,
+  external_id   TEXT NOT NULL,
+  display_name  TEXT,
+  source        TEXT,
+  is_primary    BOOLEAN,
+  picture       TEXT,
+  linked_at     DATE NOT NULL,
+  created_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  PRIMARY KEY (workspace_id, ref),
+  FOREIGN KEY (workspace_id, person_id)
+    REFERENCES engram_persons(workspace_id, id) ON DELETE CASCADE
+);
+
+-- The two query shapes the resolver needs.
+CREATE INDEX IF NOT EXISTS idx_engram_identities_person
+  ON engram_identities (workspace_id, person_id);
+CREATE INDEX IF NOT EXISTS idx_engram_identities_service_external
+  ON engram_identities (workspace_id, service, external_id);
+`;

package/dist/migrations/index.js

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

package/dist/openapi.js

@@ -58,6 +58,10 @@ const TAG_DEFS = [
     { name: "Sessions", description: "セッションの作成・取得・イベント追加" },
     { name: "Search", description: "ワークスペースコーパスへのスコアリング検索" },
     { name: "Persons", description: "person の作成・更新・検索" },
+    {
+        name: "Identities",
+        description: "外部 ID（slack: / email: など）の resolve と upsert",
+    },
     {
         name: "Workspaces (admin)",
         description: "ワークスペースの管理（管理者トークン必須）",
@@ -257,6 +261,38 @@ function buildPaths() {
                 },
             },
         }),
+        "/v1/persons/{id}/identities": tagged("Persons", {
+            get: {
+                summary: "この person のすべての identity を取得する（直近 link が先頭）。",
+                parameters: [pathParam("id", "person id。")],
+                responses: {
+                    "200": res("identity 一覧"),
+                    "401": res("認証エラー"),
+                },
+            },
+        }),
+        "/v1/identities/{ref}": tagged("Identities", {
+            put: {
+                summary: "ref（例: `slack:U12345`、`email:foo@bar.com`）で identity を upsert する。",
+                parameters: [pathParam("ref", "global identity ref（URL-encoded）。")],
+                requestBody: jsonBody("IdentityUpsert"),
+                responses: {
+                    "200": res("upsert された identity"),
+                    "400": res("リクエストボディが不正"),
+                    "404": res("person_id が見つからない"),
+                    "401": res("認証エラー"),
+                },
+            },
+            get: {
+                summary: "ref から identity を resolve する。",
+                parameters: [pathParam("ref", "global identity ref（URL-encoded）。")],
+                responses: {
+                    "200": res("identity 情報"),
+                    "404": res("ref が見つからない"),
+                    "401": res("認証エラー"),
+                },
+            },
+        }),
         "/admin/v1/workspaces": tagged("Workspaces (admin)", {
             post: {
                 summary: "ワークスペースを作成する（デフォルトで初期キーも発行する）。",

package/dist/routes/identities.d.ts

@@ -0,0 +1,14 @@
+import { Hono } from "hono";
+import type { Env } from "../context";
+import type { RouteConfig } from "./helpers";
+/**
+ * Identity routes. Mount under `/v1`:
+ *   PUT /v1/identities/:ref  upsert by global ref (e.g. `slack:U12345`)
+ *   GET /v1/identities/:ref  resolve a ref to its identity record
+ *
+ * The "list this person's identities" endpoint is exposed by the
+ * persons routes at `/v1/persons/:id/identities` because that's the
+ * natural client mental model — start from a person, fan out — not
+ * start from a ref.
+ */
+export declare function identitiesRoutes(_cfg: RouteConfig): Hono<Env>;

package/dist/routes/identities.js

@@ -0,0 +1,33 @@
+import { Hono } from "hono";
+import { identityUpsertSchema, parseJsonBody } from "../schemas";
+/**
+ * Identity routes. Mount under `/v1`:
+ *   PUT /v1/identities/:ref  upsert by global ref (e.g. `slack:U12345`)
+ *   GET /v1/identities/:ref  resolve a ref to its identity record
+ *
+ * The "list this person's identities" endpoint is exposed by the
+ * persons routes at `/v1/persons/:id/identities` because that's the
+ * natural client mental model — start from a person, fan out — not
+ * start from a ref.
+ */
+export function identitiesRoutes(_cfg) {
+    const app = new Hono();
+    app.put("/identities/:ref", async (c) => {
+        const ref = c.req.param("ref");
+        const body = await parseJsonBody(c, identityUpsertSchema);
+        if (body instanceof Response)
+            return body;
+        const identity = await c.var.ctx.storage.upsertIdentity(ref, body);
+        if (!identity)
+            return c.json({ error: "person_not_found" }, 404);
+        return c.json(identity);
+    });
+    app.get("/identities/:ref", async (c) => {
+        const ref = c.req.param("ref");
+        const identity = await c.var.ctx.storage.getIdentityByRef(ref);
+        if (!identity)
+            return c.json({ error: "identity_not_found" }, 404);
+        return c.json(identity);
+    });
+    return app;
+}

package/dist/routes/persons.js

@@ -68,6 +68,11 @@ export function personsRoutes(cfg) {
         const aliases = await c.var.ctx.storage.listAliases(id);
         return c.json({ aliases });
     });
+    app.get("/persons/:id/identities", async (c) => {
+        const id = c.req.param("id");
+        const identities = await c.var.ctx.storage.listIdentitiesByPerson(id);
+        return c.json({ identities });
+    });
     app.get("/persons/:id/sessions", async (c) => {
         const id = c.req.param("id");
         const limit = clampLimit(c, cfg.defaultListLimit, cfg.maxListLimit);

package/dist/schemas.d.ts

@@ -71,6 +71,16 @@ export declare const aliasUpsertSchema: z.ZodObject<{
     last_used: z.ZodString;
     increment: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
+export declare const identityUpsertSchema: z.ZodObject<{
+    person_id: z.ZodString;
+    service: z.ZodString;
+    external_id: z.ZodString;
+    display_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    source: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    is_primary: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    picture: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    linked_at: z.ZodString;
+}, z.core.$strip>;
 export declare const searchRequestSchema: z.ZodObject<{
     query: z.ZodUnion<readonly [z.ZodObject<{
         sessionId: z.ZodString;

package/dist/schemas.js

@@ -66,6 +66,19 @@ export const aliasUpsertSchema = z.object({
         .regex(/^\d{4}-\d{2}-\d{2}/, "expected YYYY-MM-DD"),
     increment: z.boolean().optional(),
 });
+// --- Identities -------------------------------------------------------
+export const identityUpsertSchema = z.object({
+    person_id: z.string().min(1),
+    service: z.string().min(1),
+    external_id: z.string().min(1),
+    display_name: z.string().nullable().optional(),
+    source: z.string().nullable().optional(),
+    is_primary: z.boolean().nullable().optional(),
+    picture: z.string().nullable().optional(),
+    linked_at: z
+        .string()
+        .regex(/^\d{4}-\d{2}-\d{2}/, "expected YYYY-MM-DD"),
+});
 // --- Search ----------------------------------------------------------
 const searchQuerySchema = z.union([
     z.object({ sessionId: z.string().min(1) }),

package/dist/server.js

@@ -3,6 +3,7 @@ import { log, newRequestId } from "./logger";
 import { createAdminRouter } from "./admin";
 import { sessionsRoutes } from "./routes/sessions";
 import { personsRoutes } from "./routes/persons";
+import { identitiesRoutes } from "./routes/identities";
 import { searchRoutes } from "./routes/search";
 /**
  * Build the engram HTTP app. Wiring only: this sets up cross-cutting
@@ -60,6 +61,8 @@ export function createServer(opts) {
             personSessions: "GET /v1/persons/:id/sessions",
             personAliases: "GET /v1/persons/:id/aliases",
             upsertAlias: "PUT /v1/persons/:id/aliases/:name",
+            identityByRef: "GET/PUT /v1/identities/:ref",
+            personIdentities: "GET /v1/persons/:id/identities",
         },
     }));
     app.get("/healthz", (c) => c.json({ ok: true }));
@@ -84,6 +87,7 @@ export function createServer(opts) {
     app.get("/v1/me", (c) => c.json({ workspaceId: c.var.ctx.workspaceId }));
     app.route("/v1", sessionsRoutes(cfg));
     app.route("/v1", personsRoutes(cfg));
+    app.route("/v1", identitiesRoutes(cfg));
     app.route("/v1", searchRoutes(cfg));
     return app;
 }

package/dist/storage.d.ts

@@ -1,5 +1,5 @@
 import type { Session } from "@hexis-ai/engram-core";
-import type { AliasInfo, AliasUpsert, PersonCreate, PersonInfo, PersonUpdate, SessionEvent, SessionInit } from "@hexis-ai/engram-sdk";
+import type { AliasInfo, AliasUpsert, IdentityInfo, IdentityUpsert, PersonCreate, PersonInfo, PersonUpdate, SessionEvent, SessionInit } from "@hexis-ai/engram-sdk";
 /**
  * Storage adapter interface. Each implementation owns persistence for
  * a single workspace's sessions and persons. Multi-tenancy is the host's
@@ -77,6 +77,19 @@ export interface StorageAdapter {
     } & AliasUpsert): Promise<AliasInfo | null>;
     /** A person's aliases, ordered newest-used-first. */
     listAliases(personId: string): Promise<AliasInfo[]>;
+    /**
+     * Upsert by `ref` (e.g. `slack:U12345`). Idempotent: writing the same
+     * ref multiple times converges. If the ref points to a different
+     * person than before, the row's `person_id` is updated — refs are
+     * the global handle, persons are reassignable underneath.
+     *
+     * Returns `null` if `input.person_id` does not exist.
+     */
+    upsertIdentity(ref: string, input: IdentityUpsert): Promise<IdentityInfo | null>;
+    /** Lookup by ref. Returns null if unknown. */
+    getIdentityByRef(ref: string): Promise<IdentityInfo | null>;
+    /** All identities for a person, ordered newest-linked-first. */
+    listIdentitiesByPerson(personId: string): Promise<IdentityInfo[]>;
 }
 /**
  * Pure fold of an event log into the parts a Session needs. Used by adapters

package/openapi.json

@@ -22,6 +22,10 @@
       "name": "Persons",
       "description": "person の作成・更新・検索"
     },
+    {
+      "name": "Identities",
+      "description": "外部 ID（slack: / email: など）の resolve と upsert"
+    },
     {
       "name": "Workspaces (admin)",
       "description": "ワークスペースの管理（管理者トークン必須）"
@@ -877,6 +881,104 @@
         ]
       }
     },
+    "/v1/persons/{id}/identities": {
+      "get": {
+        "summary": "この person のすべての identity を取得する（直近 link が先頭）。",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "person id。"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "identity 一覧"
+          },
+          "401": {
+            "description": "認証エラー"
+          }
+        },
+        "tags": [
+          "Persons"
+        ]
+      }
+    },
+    "/v1/identities/{ref}": {
+      "put": {
+        "summary": "ref（例: `slack:U12345`、`email:foo@bar.com`）で identity を upsert する。",
+        "parameters": [
+          {
+            "name": "ref",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "global identity ref（URL-encoded）。"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/IdentityUpsert"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "upsert された identity"
+          },
+          "400": {
+            "description": "リクエストボディが不正"
+          },
+          "401": {
+            "description": "認証エラー"
+          },
+          "404": {
+            "description": "person_id が見つからない"
+          }
+        },
+        "tags": [
+          "Identities"
+        ]
+      },
+      "get": {
+        "summary": "ref から identity を resolve する。",
+        "parameters": [
+          {
+            "name": "ref",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "global identity ref（URL-encoded）。"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "identity 情報"
+          },
+          "401": {
+            "description": "認証エラー"
+          },
+          "404": {
+            "description": "ref が見つからない"
+          }
+        },
+        "tags": [
+          "Identities"
+        ]
+      }
+    },
     "/admin/v1/workspaces": {
       "post": {
         "summary": "ワークスペースを作成する（デフォルトで初期キーも発行する）。",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hexis-ai/engram-server",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Engram server: ingest agent session events, persist via a pluggable adapter, expose search.",
   "keywords": [
     "engram",
@@ -50,7 +50,7 @@
   },
   "dependencies": {
     "@hexis-ai/engram-core": "^0.1.5",
-    "@hexis-ai/engram-sdk": "^0.4.0",
+    "@hexis-ai/engram-sdk": "^0.5.0",
     "hono": "^4.6.0",
     "zod": "^4.0.0"
   },