@retinue/agentkit 0.2.0 → 0.3.1

package/dist/adapters/memory/rate-limit.js

@@ -0,0 +1,28 @@
+/**
+ * The rate-limit counter in memory — task #248.
+ *
+ * **For tests and a single-process deployment only.** Two workers each hold their own `Map`, so each allows the
+ * full rate and a limit of 60/minute becomes 60×N. That is not a caveat to be worked around; it is why
+ * `createRedisRateLimitStore` exists, and why the cross-process test in this task's suite runs against a real
+ * Redis rather than this.
+ *
+ * Old windows are dropped on write rather than on a timer: a timer in a store would keep a process alive and
+ * would need clearing, and the number of live windows is one per tenant.
+ */
+export const createMemoryRateLimitStore = () => {
+    const counts = new Map();
+    return {
+        async consume({ tenantId, windowStartMs }) {
+            const key = `${tenantId}:${windowStartMs}`;
+            // Every other window for this tenant is over, so nothing else can be incremented again.
+            for (const existing of counts.keys()) {
+                if (existing.startsWith(`${tenantId}:`) && existing !== key)
+                    counts.delete(existing);
+            }
+            const next = (counts.get(key) ?? 0) + 1;
+            counts.set(key, next);
+            return next;
+        },
+    };
+};
+//# sourceMappingURL=rate-limit.js.map

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

@@ -0,0 +1,15 @@
+/**
+ * `ConnectionStore` over Postgres — task #261.
+ *
+ * Pure SQL over `SqlExecutor`, like every other adapter here. The store never sees a plaintext secret: it
+ * writes the four columns of a `SealedSecret` and reads them back, so an adapter cannot leak something it does
+ * not have.
+ *
+ * Every query is tenant-scoped in its `WHERE`, and there is no `findById(id)` — governing principle 1. That is
+ * not belt-and-braces over RLS; it is the layer RLS is defence in depth *for*, and #91 is the reminder that a
+ * method accepting a tenant scope and not using it typechecks perfectly.
+ */
+import type { ConnectionStore } from "../../connections/index.js";
+import type { SqlExecutor } from "./sql.js";
+export declare const createPostgresConnectionStore: (sql: SqlExecutor) => ConnectionStore;
+//# sourceMappingURL=connections.d.ts.map

package/dist/adapters/postgres/connections.js

@@ -0,0 +1,134 @@
+/**
+ * `ConnectionStore` over Postgres — task #261.
+ *
+ * Pure SQL over `SqlExecutor`, like every other adapter here. The store never sees a plaintext secret: it
+ * writes the four columns of a `SealedSecret` and reads them back, so an adapter cannot leak something it does
+ * not have.
+ *
+ * Every query is tenant-scoped in its `WHERE`, and there is no `findById(id)` — governing principle 1. That is
+ * not belt-and-braces over RLS; it is the layer RLS is defence in depth *for*, and #91 is the reminder that a
+ * method accepting a tenant scope and not using it typechecks perfectly.
+ */
+import { AgentPlatformError } from "../../core/errors.js";
+const iso = (value) => (value instanceof Date ? value.toISOString() : value);
+const toConnection = (row) => ({
+    id: row.id,
+    kind: row.kind,
+    provider: row.provider,
+    ...(row.label === null ? {} : { label: row.label }),
+    mode: row.mode,
+    scheme: row.scheme,
+    ...(row.metadata === null || Object.keys(row.metadata).length === 0 ? {} : { metadata: row.metadata }),
+    ...(row.granted_scopes === null ? {} : { grantedScopes: row.granted_scopes }),
+    sealed: {
+        keyId: row.secret_key_id,
+        algorithm: row.secret_algorithm,
+        nonce: row.secret_nonce,
+        ciphertext: row.secret_ciphertext,
+    },
+    ...(row.expires_at === null ? {} : { expiresAt: iso(row.expires_at) }),
+    createdAt: iso(row.created_at),
+    updatedAt: iso(row.updated_at),
+    ...(row.revoked_at === null ? {} : { revokedAt: iso(row.revoked_at) }),
+});
+const COLUMNS = `id, kind, provider, label, mode, scheme, metadata, granted_scopes,
+  secret_key_id, secret_algorithm, secret_nonce, secret_ciphertext,
+  expires_at, created_at, updated_at, revoked_at`;
+const notFound = (id) => new AgentPlatformError({ code: "not_found", message: `no connection "${id}" for this tenant`, retryable: false });
+export const createPostgresConnectionStore = (sql) => ({
+    async create({ tenantId, connection }) {
+        const rows = await sql.query(`INSERT INTO connections (
+         tenant_id, id, kind, provider, label, mode, scheme, metadata, granted_scopes,
+         secret_key_id, secret_algorithm, secret_nonce, secret_ciphertext, expires_at
+       ) VALUES ($1,$2,$14,$3,$4,$5,$6,$7::jsonb,$8,$9,$10,$11,$12,$13)
+       -- No upsert: a second create for the same id is a caller bug, and silently overwriting a credential is
+       -- the worst possible resolution of it.
+       RETURNING ${COLUMNS}`, [
+            tenantId,
+            connection.id,
+            connection.provider,
+            connection.label ?? null,
+            connection.mode,
+            connection.scheme,
+            JSON.stringify(connection.metadata ?? {}),
+            connection.grantedScopes === undefined ? null : [...connection.grantedScopes],
+            connection.sealed.keyId,
+            connection.sealed.algorithm,
+            connection.sealed.nonce,
+            connection.sealed.ciphertext,
+            connection.expiresAt ?? null,
+            connection.kind ?? "connection",
+        ]);
+        const row = rows[0];
+        if (row === undefined)
+            throw new AgentPlatformError({ code: "conflict", message: `connection "${connection.id}" already exists`, retryable: false });
+        return toConnection(row);
+    },
+    async get({ tenantId, id, kind }) {
+        // `revoked_at IS NULL` here rather than in the caller: a revoked connection reading as present is how a
+        // withdrawn credential gets used once more.
+        const rows = await sql.query(
+        // `kind` in the predicate, not filtered afterwards: a caller that did not ask for an app registration
+        // must not receive one, and a post-filter is a place somebody later removes.
+        `SELECT ${COLUMNS} FROM connections
+       WHERE tenant_id = $1 AND id = $2 AND revoked_at IS NULL AND kind = $3`, [tenantId, id, kind ?? "connection"]);
+        return rows[0] === undefined ? null : toConnection(rows[0]);
+    },
+    async list({ tenantId, provider, kind }) {
+        const rows = await sql.query(`SELECT ${COLUMNS} FROM connections
+       WHERE tenant_id = $1 AND revoked_at IS NULL AND ($2::text IS NULL OR provider = $2) AND kind = $3
+       ORDER BY created_at, id`, [tenantId, provider ?? null, kind ?? "connection"]);
+        return rows.map(toConnection);
+    },
+    async update({ tenantId, id, patch }) {
+        /**
+         * `COALESCE` per column, so an absent field means "leave it" rather than "set it to null".
+         *
+         * The alternative — building the SET list from the present keys — is how a patch with no fields becomes
+         * invalid SQL, and how a field named in one place and not another silently stops being updatable.
+         */
+        const rows = await sql.query(`UPDATE connections SET
+         label = COALESCE($3, label),
+         secret_key_id = COALESCE($4, secret_key_id),
+         secret_algorithm = COALESCE($5, secret_algorithm),
+         secret_nonce = COALESCE($6, secret_nonce),
+         secret_ciphertext = COALESCE($7, secret_ciphertext),
+         metadata = COALESCE($8::jsonb, metadata),
+         granted_scopes = COALESCE($9, granted_scopes),
+         expires_at = COALESCE($10, expires_at),
+         updated_at = now()
+       WHERE tenant_id = $1 AND id = $2 AND revoked_at IS NULL
+       RETURNING ${COLUMNS}`, [
+            tenantId,
+            id,
+            patch.label ?? null,
+            patch.sealed?.keyId ?? null,
+            patch.sealed?.algorithm ?? null,
+            patch.sealed?.nonce ?? null,
+            patch.sealed?.ciphertext ?? null,
+            patch.metadata === undefined ? null : JSON.stringify(patch.metadata),
+            patch.grantedScopes === undefined ? null : [...patch.grantedScopes],
+            patch.expiresAt ?? null,
+        ]);
+        if (rows[0] === undefined)
+            throw notFound(id);
+        return toConnection(rows[0]);
+    },
+    async revoke({ tenantId, id }) {
+        const rows = await sql.query(`UPDATE connections SET revoked_at = now(), updated_at = now()
+       WHERE tenant_id = $1 AND id = $2 AND revoked_at IS NULL
+       RETURNING id`, [tenantId, id]);
+        if (rows[0] !== undefined)
+            return;
+        // Idempotent: already revoked is success, so a retried disconnect need not distinguish it from a failure.
+        const existing = await sql.query(`SELECT id FROM connections WHERE tenant_id = $1 AND id = $2`, [tenantId, id]);
+        if (existing[0] === undefined)
+            throw notFound(id);
+    },
+    async purge({ tenantId }) {
+        // The one hard delete — `docs/18`. A soft-deleted credential is still a credential.
+        const rows = await sql.query(`DELETE FROM connections WHERE tenant_id = $1 RETURNING id`, [tenantId]);
+        return rows.length;
+    },
+});
+//# sourceMappingURL=connections.js.map

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

@@ -0,0 +1,24 @@
+/**
+ * Postgres `GraphStore` — REQ-064 (#270), task #271.
+ *
+ * **Contributions are the stored truth; the entity and relationship tables are a cache of their merge.**
+ *
+ * That split is the whole design, and it is worth being explicit about why the obvious alternative is wrong.
+ * Storing merged entities alone and mutating them per source needs reference counting — "how many sources still
+ * name this entity" — and reference counting is the thing everybody gets wrong under concurrency. Storing what
+ * each source asserted and rebuilding the merge makes pruning a consequence rather than a bookkeeping exercise:
+ * an entity exists precisely while some contribution names it, and nothing has to remember why.
+ *
+ * The merge is recomputed in TypeScript rather than SQL. A `jsonb_array_elements` aggregation could do it, but
+ * the merge rule — lexicographically-first canonical name, longest description, unioned surface forms, weight
+ * as the provenance count — would then exist twice, in two languages, and the reference adapter's copy is the
+ * one the conformance suite tests. One rule in one place is worth a round trip.
+ *
+ * Provenance is enforced by a `CHECK` constraint as well as here, deliberately. The application check gives a
+ * message that explains itself; the constraint is what still holds when somebody writes to these tables from a
+ * migration or a console.
+ */
+import type { GraphStore } from "../../persistence/index.js";
+import type { SqlExecutor } from "./sql.js";
+export declare const createPostgresGraphStore: (sql: SqlExecutor) => GraphStore;
+//# sourceMappingURL=graph.d.ts.map

package/dist/adapters/postgres/graph.js

@@ -0,0 +1,325 @@
+/**
+ * Postgres `GraphStore` — REQ-064 (#270), task #271.
+ *
+ * **Contributions are the stored truth; the entity and relationship tables are a cache of their merge.**
+ *
+ * That split is the whole design, and it is worth being explicit about why the obvious alternative is wrong.
+ * Storing merged entities alone and mutating them per source needs reference counting — "how many sources still
+ * name this entity" — and reference counting is the thing everybody gets wrong under concurrency. Storing what
+ * each source asserted and rebuilding the merge makes pruning a consequence rather than a bookkeeping exercise:
+ * an entity exists precisely while some contribution names it, and nothing has to remember why.
+ *
+ * The merge is recomputed in TypeScript rather than SQL. A `jsonb_array_elements` aggregation could do it, but
+ * the merge rule — lexicographically-first canonical name, longest description, unioned surface forms, weight
+ * as the provenance count — would then exist twice, in two languages, and the reference adapter's copy is the
+ * one the conformance suite tests. One rule in one place is worth a round trip.
+ *
+ * Provenance is enforced by a `CHECK` constraint as well as here, deliberately. The application check gives a
+ * message that explains itself; the constraint is what still holds when somebody writes to these tables from a
+ * migration or a console.
+ */
+import { AgentPlatformError } from "../../core/errors.js";
+const iso = (value) => (value instanceof Date ? value.toISOString() : value);
+const toEntity = (row) => ({
+    id: row.id,
+    name: row.name,
+    type: row.type,
+    ...(row.description === null ? {} : { description: row.description }),
+    surfaceForms: row.surface_forms,
+    provenance: row.provenance,
+});
+const toRelationship = (row) => ({
+    id: row.id,
+    fromId: row.from_id,
+    toId: row.to_id,
+    type: row.type,
+    ...(row.description === null ? {} : { description: row.description }),
+    weight: Number(row.weight),
+    provenance: row.provenance,
+});
+const toCommunity = (row) => ({
+    id: row.id,
+    level: Number(row.level),
+    entityIds: row.entity_ids,
+    relationshipIds: row.relationship_ids,
+    chunkIds: row.chunk_ids,
+    fingerprint: row.fingerprint,
+    ...(row.summary === null ? {} : { summary: row.summary }),
+    ...(row.summary_fingerprint === null ? {} : { summaryFingerprint: row.summary_fingerprint }),
+    ...(row.summarised_at === null ? {} : { summarisedAt: iso(row.summarised_at) }),
+});
+const uniqueSorted = (values) => [...new Set(values)].sort();
+const byId = (a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+/** Rebuilds the merged graph from every contribution. Mirrors `mergeContributions` — see the header. */
+const mergeAll = (contributions) => {
+    const entities = new Map();
+    const relationships = new Map();
+    for (const contribution of contributions) {
+        for (const entity of contribution.entities) {
+            const existing = entities.get(entity.id);
+            if (existing === undefined) {
+                entities.set(entity.id, entity);
+                continue;
+            }
+            const description = (entity.description ?? "").length > (existing.description ?? "").length ? entity.description : existing.description;
+            entities.set(entity.id, {
+                id: entity.id,
+                name: existing.name < entity.name ? existing.name : entity.name,
+                type: existing.type,
+                ...(description === undefined ? {} : { description }),
+                surfaceForms: uniqueSorted([...existing.surfaceForms, ...entity.surfaceForms]),
+                provenance: uniqueSorted([...existing.provenance, ...entity.provenance]),
+            });
+        }
+    }
+    for (const contribution of contributions) {
+        for (const edge of contribution.relationships) {
+            const existing = relationships.get(edge.id);
+            if (existing === undefined) {
+                relationships.set(edge.id, edge);
+                continue;
+            }
+            const description = (edge.description ?? "").length > (existing.description ?? "").length ? edge.description : existing.description;
+            const provenance = uniqueSorted([...existing.provenance, ...edge.provenance]);
+            relationships.set(edge.id, {
+                ...existing,
+                ...(description === undefined ? {} : { description }),
+                weight: provenance.length,
+                provenance,
+            });
+        }
+    }
+    const kept = [...relationships.values()].filter((edge) => entities.has(edge.fromId) && entities.has(edge.toId));
+    return { entities: [...entities.values()].sort(byId), relationships: kept.sort(byId) };
+};
+const assertProvenance = (contribution) => {
+    for (const row of [...contribution.entities, ...contribution.relationships]) {
+        if (row.provenance.length === 0)
+            throw new AgentPlatformError({
+                code: "invalid_input",
+                message: `${row.id} has no provenance; a graph claim with no chunk behind it is one the model would cite`,
+                retryable: false,
+            });
+    }
+};
+export const createPostgresGraphStore = (sql) => {
+    /** Every contribution for a tenant, which is what the merge is derived from. */
+    const contributionsOf = async (tenantId) => {
+        const rows = await sql.query(`SELECT entities, relationships FROM knowledge_graph_contributions
+        WHERE tenant_id = $1 ORDER BY source_type, source_id`, [tenantId]);
+        return rows.map((row) => ({
+            entities: (row.entities ?? []),
+            relationships: (row.relationships ?? []),
+        }));
+    };
+    /**
+     * Rewrites the merged tables from the contributions.
+     *
+     * Delete-then-insert rather than an upsert-and-sweep, for the reason `replaceSource` is: a partial merge is a
+     * graph that is half old and half new, and no reader can tell. Callers run this inside the same unit of work
+     * as the contribution write.
+     */
+    const rebuild = async (tenantId) => {
+        const merged = mergeAll(await contributionsOf(tenantId));
+        await sql.query(`DELETE FROM knowledge_graph_relationships WHERE tenant_id = $1`, [tenantId]);
+        await sql.query(`DELETE FROM knowledge_graph_entities WHERE tenant_id = $1`, [tenantId]);
+        for (const entity of merged.entities) {
+            await sql.query(`INSERT INTO knowledge_graph_entities
+           (tenant_id, id, name, type, description, surface_forms, provenance)
+         VALUES ($1, $2, $3, $4, $5, $6, $7)`, [tenantId, entity.id, entity.name, entity.type, entity.description ?? null, entity.surfaceForms, entity.provenance]);
+        }
+        for (const edge of merged.relationships) {
+            await sql.query(`INSERT INTO knowledge_graph_relationships
+           (tenant_id, id, from_id, to_id, type, description, weight, provenance)
+         VALUES ($1, $2, $3, $4, $5, $6, $7, $8)`, [tenantId, edge.id, edge.fromId, edge.toId, edge.type, edge.description ?? null, edge.weight, edge.provenance]);
+        }
+        return { entities: merged.entities.length, relationships: merged.relationships.length };
+    };
+    const countEntities = async (tenantId) => {
+        const rows = await sql.query(`SELECT count(*)::text AS n FROM knowledge_graph_entities WHERE tenant_id = $1`, [tenantId]);
+        return Number(rows[0]?.n ?? 0);
+    };
+    return {
+        async getSettings({ tenantId }) {
+            const rows = await sql.query(`SELECT enabled, updated_at FROM knowledge_graph_settings WHERE tenant_id = $1`, [tenantId]);
+            const row = rows[0];
+            // Absent means off. A tenant that has never been configured must not be able to start paying for
+            // extraction because a row was missing rather than false.
+            return row === undefined
+                ? { enabled: false, updatedAt: "1970-01-01T00:00:00.000Z" }
+                : { enabled: row.enabled, updatedAt: iso(row.updated_at) };
+        },
+        async setEnabled({ tenantId, enabled, at }) {
+            await sql.query(`INSERT INTO knowledge_graph_settings (tenant_id, enabled, updated_at)
+         VALUES ($1, $2, $3)
+         ON CONFLICT (tenant_id) DO UPDATE SET enabled = EXCLUDED.enabled, updated_at = EXCLUDED.updated_at`, [tenantId, enabled, at]);
+            return { enabled, updatedAt: at };
+        },
+        async setSourceEnabled({ tenantId, sourceType, sourceId, enabled }) {
+            // Never consults the tenant switch — AC-2. The flag outlives it in both directions.
+            await sql.query(`INSERT INTO knowledge_graph_sources (tenant_id, source_type, source_id, enabled)
+         VALUES ($1, $2, $3, $4)
+         ON CONFLICT (tenant_id, source_type, source_id) DO UPDATE SET enabled = EXCLUDED.enabled`, [tenantId, sourceType, sourceId, enabled]);
+        },
+        async isSourceEnabled({ tenantId, sourceType, sourceId }) {
+            const rows = await sql.query(`SELECT enabled FROM knowledge_graph_sources
+          WHERE tenant_id = $1 AND source_type = $2 AND source_id = $3`, [tenantId, sourceType, sourceId]);
+            return rows[0]?.enabled === true;
+        },
+        async listEnabledSources({ tenantId, limit, cursor }) {
+            const offset = cursor === undefined ? 0 : Number.parseInt(cursor, 10) || 0;
+            const rows = await sql.query(`SELECT source_type, source_id FROM knowledge_graph_sources
+          WHERE tenant_id = $1 AND enabled
+          ORDER BY source_type, source_id
+          LIMIT $2 OFFSET $3`, [tenantId, limit + 1, offset]);
+            const items = rows.slice(0, limit).map((row) => ({
+                sourceType: row.source_type,
+                sourceId: row.source_id,
+            }));
+            return rows.length > limit ? { items, nextCursor: String(offset + limit) } : { items };
+        },
+        async replaceSourceGraph({ tenantId, sourceType, sourceId, contribution }) {
+            assertProvenance(contribution);
+            const before = await countEntities(tenantId);
+            if (contribution.entities.length === 0 && contribution.relationships.length === 0) {
+                // An empty contribution is a withdrawal, not an empty row: leaving `{"entities":[]}` behind would make
+                // every future merge read a row that says nothing.
+                await sql.query(`DELETE FROM knowledge_graph_contributions WHERE tenant_id = $1 AND source_type = $2 AND source_id = $3`, [tenantId, sourceType, sourceId]);
+            }
+            else {
+                await sql.query(`INSERT INTO knowledge_graph_contributions (tenant_id, source_type, source_id, entities, relationships)
+           VALUES ($1, $2, $3, $4::jsonb, $5::jsonb)
+           ON CONFLICT (tenant_id, source_type, source_id)
+           DO UPDATE SET entities = EXCLUDED.entities,
+                         relationships = EXCLUDED.relationships,
+                         updated_at = now()`, [tenantId, sourceType, sourceId, JSON.stringify(contribution.entities), JSON.stringify(contribution.relationships)]);
+            }
+            const rebuilt = await rebuild(tenantId);
+            return { ...rebuilt, pruned: Math.max(0, before - rebuilt.entities) };
+        },
+        async deleteSourceGraph({ tenantId, sourceType, sourceId }) {
+            const before = await countEntities(tenantId);
+            await sql.query(`DELETE FROM knowledge_graph_contributions WHERE tenant_id = $1 AND source_type = $2 AND source_id = $3`, [tenantId, sourceType, sourceId]);
+            const rebuilt = await rebuild(tenantId);
+            return { pruned: Math.max(0, before - rebuilt.entities) };
+        },
+        async getEntity({ tenantId, id }) {
+            const rows = await sql.query(`SELECT id, name, type, description, surface_forms, provenance
+           FROM knowledge_graph_entities WHERE tenant_id = $1 AND id = $2`, [tenantId, id]);
+            const row = rows[0];
+            return row === undefined ? null : toEntity(row);
+        },
+        async getEntities({ tenantId, ids }) {
+            if (ids.length === 0)
+                return [];
+            const rows = await sql.query(`SELECT id, name, type, description, surface_forms, provenance
+           FROM knowledge_graph_entities WHERE tenant_id = $1 AND id = ANY($2) ORDER BY id`, [tenantId, [...ids]]);
+            return rows.map(toEntity);
+        },
+        async resolveEntities({ tenantId, normalisedNames }) {
+            if (normalisedNames.length === 0)
+                return [];
+            const rows = await sql.query(`SELECT id, name, type, description, surface_forms, provenance
+           FROM knowledge_graph_entities
+          -- The id is \`type:normalisedName\`, and \`normaliseName\` cannot produce a colon, so everything after
+          -- the first one is the name. Matching on that keeps query-side and index-side resolution identical
+          -- without a second stored column to drift.
+          WHERE tenant_id = $1 AND substring(id from position(':' in id) + 1) = ANY($2)
+          ORDER BY id`, [tenantId, [...normalisedNames]]);
+            return rows.map(toEntity);
+        },
+        async listEntities({ tenantId, limit, cursor, type }) {
+            const offset = cursor === undefined ? 0 : Number.parseInt(cursor, 10) || 0;
+            const rows = await sql.query(`SELECT id, name, type, description, surface_forms, provenance
+           FROM knowledge_graph_entities
+          WHERE tenant_id = $1 AND ($2::text IS NULL OR type = $2)
+          ORDER BY id
+          LIMIT $3 OFFSET $4`, [tenantId, type ?? null, limit + 1, offset]);
+            const items = rows.slice(0, limit).map(toEntity);
+            return rows.length > limit ? { items, nextCursor: String(offset + limit) } : { items };
+        },
+        async neighbours({ tenantId, entityIds, limit }) {
+            if (entityIds.length === 0 || limit <= 0)
+                return [];
+            const rows = await sql.query(`SELECT id, from_id, to_id, type, description, weight, provenance
+           FROM knowledge_graph_relationships
+          WHERE tenant_id = $1 AND (from_id = ANY($2) OR to_id = ANY($2))
+          -- Heaviest first, then by id: a total order, so a truncated traversal is reproducible.
+          ORDER BY weight DESC, id
+          LIMIT $3`, [tenantId, [...entityIds], limit]);
+            return rows.map(toRelationship);
+        },
+        async replaceCommunities({ tenantId, communities }) {
+            // Read before the delete, so summaries can be carried over. One query rather than per-community lookups.
+            const previous = new Map((await sql.query(`SELECT id, summary, summary_fingerprint, summarised_at
+               FROM knowledge_graph_communities WHERE tenant_id = $1`, [tenantId])).map((row) => [row.id, row]));
+            await sql.query(`DELETE FROM knowledge_graph_communities WHERE tenant_id = $1`, [tenantId]);
+            let summariesKept = 0;
+            for (const community of communities) {
+                const before = previous.get(community.id);
+                // Identical membership only — see the memory adapter for why an id match is not enough.
+                const keep = before?.summary != null && before.summary_fingerprint === community.fingerprint;
+                if (keep)
+                    summariesKept += 1;
+                await sql.query(`INSERT INTO knowledge_graph_communities
+             (tenant_id, id, level, entity_ids, relationship_ids, chunk_ids, fingerprint,
+              summary, summary_fingerprint, summarised_at)
+           VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)`, [
+                    tenantId,
+                    community.id,
+                    community.level,
+                    community.entityIds,
+                    community.relationshipIds,
+                    community.chunkIds,
+                    community.fingerprint,
+                    keep ? before?.summary ?? null : null,
+                    keep ? before?.summary_fingerprint ?? null : null,
+                    keep ? (before?.summarised_at === null || before?.summarised_at === undefined ? null : iso(before.summarised_at)) : null,
+                ]);
+            }
+            return { written: communities.length, summariesKept };
+        },
+        async listCommunities({ tenantId, limit, cursor, level }) {
+            const offset = cursor === undefined ? 0 : Number.parseInt(cursor, 10) || 0;
+            const rows = await sql.query(`SELECT id, level, entity_ids, relationship_ids, chunk_ids, fingerprint, summary, summary_fingerprint, summarised_at
+           FROM knowledge_graph_communities
+          WHERE tenant_id = $1 AND ($2::int IS NULL OR level = $2)
+          ORDER BY level, id
+          LIMIT $3 OFFSET $4`, [tenantId, level ?? null, limit + 1, offset]);
+            const items = rows.slice(0, limit).map(toCommunity);
+            return rows.length > limit ? { items, nextCursor: String(offset + limit) } : { items };
+        },
+        async getCommunity({ tenantId, id }) {
+            const rows = await sql.query(`SELECT id, level, entity_ids, relationship_ids, chunk_ids, fingerprint, summary, summary_fingerprint, summarised_at
+           FROM knowledge_graph_communities WHERE tenant_id = $1 AND id = $2`, [tenantId, id]);
+            const row = rows[0];
+            return row === undefined ? null : toCommunity(row);
+        },
+        async setCommunitySummary({ tenantId, id, summary, fingerprint, at }) {
+            await sql.query(`UPDATE knowledge_graph_communities
+            SET summary = $3, summary_fingerprint = $4, summarised_at = $5
+          WHERE tenant_id = $1 AND id = $2`, [tenantId, id, summary, fingerprint, at]);
+        },
+        async fingerprint({ tenantId }) {
+            // Read from the merged tables, not recomputed — the point is to prove *this adapter's stored state*
+            // matches, and recomputing would fingerprint the merge function instead of the database.
+            const entities = await sql.query(`SELECT id, name, type, description, surface_forms, provenance
+           FROM knowledge_graph_entities WHERE tenant_id = $1 ORDER BY id`, [tenantId]);
+            const relationships = await sql.query(`SELECT id, from_id, to_id, type, description, weight, provenance
+           FROM knowledge_graph_relationships WHERE tenant_id = $1 ORDER BY id`, [tenantId]);
+            return [
+                ...entities.map((row) => [
+                    "E",
+                    row.id,
+                    row.name,
+                    row.type,
+                    row.description ?? "",
+                    [...row.surface_forms].sort().join(","),
+                    [...row.provenance].sort().join(","),
+                ].join("")),
+                ...relationships.map((row) => ["R", row.id, row.type, String(Number(row.weight)), row.description ?? "", [...row.provenance].sort().join(",")].join("")),
+            ].join("\n");
+        },
+    };
+};
+//# sourceMappingURL=graph.js.map

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

@@ -27,9 +27,11 @@ export * from "./files.js";
 export * from "./artifacts.js";
 export * from "./artifact-exports.js";
 export * from "./knowledge.js";
+export * from "./graph.js";
 export * from "./rollups.js";
 export * from "./evaluation.js";
 export * from "./retention.js";
 export * from "./file-content.js";
 export * from "./flows.js";
+export * from "./connections.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/adapters/postgres/index.js

@@ -27,9 +27,11 @@ export * from "./files.js";
 export * from "./artifacts.js";
 export * from "./artifact-exports.js";
 export * from "./knowledge.js";
+export * from "./graph.js";
 export * from "./rollups.js";
 export * from "./evaluation.js";
 export * from "./retention.js";
 export * from "./file-content.js";
 export * from "./flows.js";
+export * from "./connections.js";
 //# sourceMappingURL=index.js.map