@grackle-ai/plugin-knowledge 0.119.0 → 0.121.0

package/dist/entity-sync.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Incremental entity projection via the domain event bus (#1258).
+ *
+ * Subscribes to entity mutation events and projects/unprojects the affected
+ * node low-latency, as an optimization on top of the reconciliation phase
+ * (which remains the correctness backbone). Only events with a precise entity
+ * id in their payload are handled here; coarse events (e.g. `environment.changed`
+ * with an empty payload) and sessions/transcripts are left to the phase.
+ *
+ * Fire-and-forget: handler errors are logged, never propagated — a missed
+ * projection is reconciled on the next scan.
+ *
+ * @module
+ */
+import type { PluginContext, Disposable } from "@grackle-ai/plugin-sdk";
+/**
+ * Subscribe to entity mutation events and incrementally project them.
+ *
+ * @returns A {@link Disposable} that unsubscribes from the event bus.
+ */
+export declare function createEntitySyncSubscriber(ctx: PluginContext): Disposable;
+//# sourceMappingURL=entity-sync.d.ts.map

package/dist/entity-sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-sync.d.ts","sourceRoot":"","sources":["../src/entity-sync.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAgB,aAAa,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAoGtF;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,aAAa,GAAG,UAAU,CAOzE"}

package/dist/entity-sync.js

@@ -0,0 +1,116 @@
+/**
+ * Incremental entity projection via the domain event bus (#1258).
+ *
+ * Subscribes to entity mutation events and projects/unprojects the affected
+ * node low-latency, as an optimization on top of the reconciliation phase
+ * (which remains the correctness backbone). Only events with a precise entity
+ * id in their payload are handled here; coarse events (e.g. `environment.changed`
+ * with an empty payload) and sessions/transcripts are left to the phase.
+ *
+ * Fire-and-forget: handler errors are logged, never propagated — a missed
+ * projection is reconciled on the next scan.
+ *
+ * @module
+ */
+import { taskStore, workspaceStore, personaStore } from "@grackle-ai/database";
+import { logger } from "./logger.js";
+import { getKnowledgeEmbedder } from "./knowledge-init.js";
+import { isNeo4jHealthy } from "./knowledge-health.js";
+import { projectTask, unprojectTask, projectWorkspace, projectPersona, unprojectPersona, unprojectEnvironment, } from "./projection/project-entity.js";
+/** Read a non-empty string field from an event payload, or `undefined`. */
+function stringField(payload, key) {
+    const value = payload[key];
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+/** Dispatch one entity mutation event to the projection. */
+async function handleEvent(event) {
+    // Only project when knowledge is initialized and Neo4j is reachable; otherwise
+    // the reconciliation phase will converge the graph once it recovers.
+    if (!getKnowledgeEmbedder() || !isNeo4jHealthy()) {
+        return;
+    }
+    const { payload } = event;
+    switch (event.type) {
+        case "task.created":
+        case "task.updated":
+        case "task.started":
+        case "task.completed":
+        case "task.reparented": {
+            const taskId = stringField(payload, "taskId");
+            if (!taskId) {
+                return;
+            }
+            const task = taskStore.getTask(taskId);
+            if (task) {
+                await projectTask(task);
+            }
+            break;
+        }
+        case "task.deleted": {
+            const taskId = stringField(payload, "taskId");
+            if (taskId) {
+                await unprojectTask(taskId);
+            }
+            break;
+        }
+        case "workspace.created":
+        case "workspace.updated":
+        case "workspace.archived": {
+            // Archive is not a delete — the row remains (status="archived") and the
+            // node is re-projected with the updated status.
+            const workspaceId = stringField(payload, "workspaceId");
+            if (!workspaceId) {
+                return;
+            }
+            const workspace = workspaceStore.getWorkspace(workspaceId);
+            if (workspace) {
+                await projectWorkspace(workspace);
+            }
+            break;
+        }
+        case "persona.created":
+        case "persona.updated": {
+            const personaId = stringField(payload, "personaId");
+            if (!personaId) {
+                return;
+            }
+            const persona = personaStore.getPersona(personaId);
+            if (persona) {
+                await projectPersona(persona);
+            }
+            break;
+        }
+        case "persona.deleted": {
+            const personaId = stringField(payload, "personaId");
+            if (personaId) {
+                await unprojectPersona(personaId);
+            }
+            break;
+        }
+        case "environment.removed": {
+            const environmentId = stringField(payload, "environmentId");
+            if (environmentId) {
+                await unprojectEnvironment(environmentId);
+            }
+            break;
+        }
+        default:
+            // sessions, transcript chunks, environment.changed (empty payload),
+            // and non-entity events are handled by the reconciliation phase.
+            break;
+    }
+}
+/**
+ * Subscribe to entity mutation events and incrementally project them.
+ *
+ * @returns A {@link Disposable} that unsubscribes from the event bus.
+ */
+export function createEntitySyncSubscriber(ctx) {
+    const unsubscribe = ctx.subscribe((event) => {
+        handleEvent(event).catch((err) => {
+            logger.error({ err, eventType: event.type }, "Knowledge entity sync failed");
+        });
+    });
+    return { dispose: unsubscribe };
+}
+//# sourceMappingURL=entity-sync.js.map

package/dist/entity-sync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-sync.js","sourceRoot":"","sources":["../src/entity-sync.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAC/E,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EACL,WAAW,EACX,aAAa,EACb,gBAAgB,EAChB,cAAc,EACd,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,gCAAgC,CAAC;AAExC,2EAA2E;AAC3E,SAAS,WAAW,CAAC,OAAgC,EAAE,GAAW;IAChE,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAC3B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AAC3E,CAAC;AAED,4DAA4D;AAC5D,KAAK,UAAU,WAAW,CAAC,KAAmB;IAC5C,+EAA+E;IAC/E,qEAAqE;IACrE,IAAI,CAAC,oBAAoB,EAAE,IAAI,CAAC,cAAc,EAAE,EAAE,CAAC;QACjD,OAAO;IACT,CAAC;IAED,MAAM,EAAE,OAAO,EAAE,GAAG,KAAK,CAAC;IAC1B,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;QACnB,KAAK,cAAc,CAAC;QACpB,KAAK,cAAc,CAAC;QACpB,KAAK,cAAc,CAAC;QACpB,KAAK,gBAAgB,CAAC;QACtB,KAAK,iBAAiB,CAAC,CAAC,CAAC;YACvB,MAAM,MAAM,GAAG,WAAW,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;YAC9C,IAAI,CAAC,MAAM,EAAE,CAAC;gBACZ,OAAO;YACT,CAAC;YACD,MAAM,IAAI,GAAG,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YACvC,IAAI,IAAI,EAAE,CAAC;gBACT,MAAM,WAAW,CAAC,IAAI,CAAC,CAAC;YAC1B,CAAC;YACD,MAAM;QACR,CAAC;QACD,KAAK,cAAc,CAAC,CAAC,CAAC;YACpB,MAAM,MAAM,GAAG,WAAW,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;YAC9C,IAAI,MAAM,EAAE,CAAC;gBACX,MAAM,aAAa,CAAC,MAAM,CAAC,CAAC;YAC9B,CAAC;YACD,MAAM;QACR,CAAC;QACD,KAAK,mBAAmB,CAAC;QACzB,KAAK,mBAAmB,CAAC;QACzB,KAAK,oBAAoB,CAAC,CAAC,CAAC;YAC1B,wEAAwE;YACxE,gDAAgD;YAChD,MAAM,WAAW,GAAG,WAAW,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;YACxD,IAAI,CAAC,WAAW,EAAE,CAAC;gBACjB,OAAO;YACT,CAAC;YACD,MAAM,SAAS,GAAG,cAAc,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC;YAC3D,IAAI,SAAS,EAAE,CAAC;gBACd,MAAM,gBAAgB,CAAC,SAAS,CAAC,CAAC;YACpC,CAAC;YACD,MAAM;QACR,CAAC;QACD,KAAK,iBAAiB,CAAC;QACvB,KAAK,iBAAiB,CAAC,CAAC,CAAC;YACvB,MAAM,SAAS,GAAG,WAAW,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;YACpD,IAAI,CAAC,SAAS,EAAE,CAAC;gBACf,OAAO;YACT,CAAC;YACD,MAAM,OAAO,GAAG,YAAY,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;YACnD,IAAI,OAAO,EAAE,CAAC;gBACZ,MAAM,cAAc,CAAC,OAAO,CAAC,CAAC;YAChC,CAAC;YACD,MAAM;QACR,CAAC;QACD,KAAK,iBAAiB,CAAC,CAAC,CAAC;YACvB,MAAM,SAAS,GAAG,WAAW,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;YACpD,IAAI,SAAS,EAAE,CAAC;gBACd,MAAM,gBAAgB,CAAC,SAAS,CAAC,CAAC;YACpC,CAAC;YACD,MAAM;QACR,CAAC;QACD,KAAK,qBAAqB,CAAC,CAAC,CAAC;YAC3B,MAAM,aAAa,GAAG,WAAW,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC;YAC5D,IAAI,aAAa,EAAE,CAAC;gBAClB,MAAM,oBAAoB,CAAC,aAAa,CAAC,CAAC;YAC5C,CAAC;YACD,MAAM;QACR,CAAC;QACD;YACE,oEAAoE;YACpE,iEAAiE;YACjE,MAAM;IACV,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,0BAA0B,CAAC,GAAkB;IAC3D,MAAM,WAAW,GAAG,GAAG,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE;QAC1C,WAAW,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;YACxC,MAAM,CAAC,KAAK,CAAC,EAAE,GAAG,EAAE,SAAS,EAAE,KAAK,CAAC,IAAI,EAAE,EAAE,8BAA8B,CAAC,CAAC;QAC/E,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IACH,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC;AAClC,CAAC"}

package/dist/knowledge-init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"knowledge-init.d.ts","sourceRoot":"","sources":["../src/knowledge-init.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAIL,WAAW,IAAI,gBAAgB,EAE/B,KAAK,QAAQ,EACd,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAE5D,+EAA+E;AAC/E,OAAO,EAAE,gBAAgB,EAAE,CAAC;AAK5B,qFAAqF;AACrF,wBAAgB,oBAAoB,IAAI,QAAQ,GAAG,SAAS,CAE3D;AAMD;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CA0BpF"}
+{"version":3,"file":"knowledge-init.d.ts","sourceRoot":"","sources":["../src/knowledge-init.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAIL,WAAW,IAAI,gBAAgB,EAG/B,KAAK,QAAQ,EACd,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAG5D,+EAA+E;AAC/E,OAAO,EAAE,gBAAgB,EAAE,CAAC;AAK5B,qFAAqF;AACrF,wBAAgB,oBAAoB,IAAI,QAAQ,GAAG,SAAS,CAE3D;AAMD;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CAqCpF"}

package/dist/knowledge-init.js

@@ -8,7 +8,8 @@
  *
  * @module
  */
-import { openNeo4j, initSchema, closeNeo4j, healthCheck as neo4jHealthCheck, createLocalEmbedder, } from "@grackle-ai/knowledge";
+import { openNeo4j, initSchema, closeNeo4j, healthCheck as neo4jHealthCheck, createLocalEmbedder, listRecentNodes, } from "@grackle-ai/knowledge";
+import { rebuild } from "./projection/rebuild.js";
 /** Re-export Neo4j health check for use by the reconciliation health phase. */
 export { neo4jHealthCheck };
 /** Module-level embedder, available after initKnowledge() completes. */
@@ -36,6 +37,16 @@ export async function initKnowledge(ctx) {
     try {
         await initSchema(embedder.dimensions);
         knowledgeEmbedder = embedder;
+        // Startup-if-empty: a fresh or wiped graph re-projects itself from SQL +
+        // session logs (recovery = re-project, never replay). Runs in the background
+        // so a large rebuild (CPU-bound embeddings) doesn't block plugin init.
+        const recent = await listRecentNodes(1);
+        if (recent.nodes.length === 0) {
+            ctx.logger.info("Knowledge graph is empty — starting background rebuild from SQL + logs");
+            void rebuild(embedder).catch((err) => {
+                ctx.logger.error({ err }, "Knowledge graph rebuild failed");
+            });
+        }
         ctx.logger.info("Knowledge graph subsystem ready");
         return async () => {
             ctx.logger.info("Shutting down knowledge graph subsystem");

package/dist/knowledge-init.js.map

@@ -1 +1 @@
-{"version":3,"file":"knowledge-init.js","sourceRoot":"","sources":["../src/knowledge-init.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,SAAS,EACT,UAAU,EACV,UAAU,EACV,WAAW,IAAI,gBAAgB,EAC/B,mBAAmB,GAEpB,MAAM,uBAAuB,CAAC;AAG/B,+EAA+E;AAC/E,OAAO,EAAE,gBAAgB,EAAE,CAAC;AAE5B,wEAAwE;AACxE,IAAI,iBAAuC,CAAC;AAE5C,qFAAqF;AACrF,MAAM,UAAU,oBAAoB;IAClC,OAAO,iBAAiB,CAAC;AAC3B,CAAC;AAED,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,GAAkB;IACpD,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,wCAAwC,CAAC,CAAC;IAE1D,MAAM,QAAQ,GAAa,mBAAmB,EAAE,CAAC;IAEjD,MAAM,SAAS,EAAE,CAAC;IAElB,IAAI,CAAC;QACH,MAAM,UAAU,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;QAEtC,iBAAiB,GAAG,QAAQ,CAAC;QAE7B,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,iCAAiC,CAAC,CAAC;QAEnD,OAAO,KAAK,IAAmB,EAAE;YAC/B,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,yCAAyC,CAAC,CAAC;YAC3D,iBAAiB,GAAG,SAAS,CAAC;YAC9B,MAAM,UAAU,EAAE,CAAC;YACnB,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,mCAAmC,CAAC,CAAC;QACvD,CAAC,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,uCAAuC;QACvC,iBAAiB,GAAG,SAAS,CAAC;QAC9B,MAAM,UAAU,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QACnC,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC"}
+{"version":3,"file":"knowledge-init.js","sourceRoot":"","sources":["../src/knowledge-init.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,SAAS,EACT,UAAU,EACV,UAAU,EACV,WAAW,IAAI,gBAAgB,EAC/B,mBAAmB,EACnB,eAAe,GAEhB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAElD,+EAA+E;AAC/E,OAAO,EAAE,gBAAgB,EAAE,CAAC;AAE5B,wEAAwE;AACxE,IAAI,iBAAuC,CAAC;AAE5C,qFAAqF;AACrF,MAAM,UAAU,oBAAoB;IAClC,OAAO,iBAAiB,CAAC;AAC3B,CAAC;AAED,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,GAAkB;IACpD,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,wCAAwC,CAAC,CAAC;IAE1D,MAAM,QAAQ,GAAa,mBAAmB,EAAE,CAAC;IAEjD,MAAM,SAAS,EAAE,CAAC;IAElB,IAAI,CAAC;QACH,MAAM,UAAU,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;QAEtC,iBAAiB,GAAG,QAAQ,CAAC;QAE7B,yEAAyE;QACzE,6EAA6E;QAC7E,uEAAuE;QACvE,MAAM,MAAM,GAAG,MAAM,eAAe,CAAC,CAAC,CAAC,CAAC;QACxC,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC9B,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,wEAAwE,CAAC,CAAC;YAC1F,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;gBAC5C,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,GAAG,EAAE,EAAE,gCAAgC,CAAC,CAAC;YAC9D,CAAC,CAAC,CAAC;QACL,CAAC;QAED,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,iCAAiC,CAAC,CAAC;QAEnD,OAAO,KAAK,IAAmB,EAAE;YAC/B,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,yCAAyC,CAAC,CAAC;YAC3D,iBAAiB,GAAG,SAAS,CAAC;YAC9B,MAAM,UAAU,EAAE,CAAC;YACnB,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,mCAAmC,CAAC,CAAC;QACvD,CAAC,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,uCAAuC;QACvC,iBAAiB,GAAG,SAAS,CAAC;QAC9B,MAAM,UAAU,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QACnC,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC"}

package/dist/knowledge-plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"knowledge-plugin.d.ts","sourceRoot":"","sources":["../src/knowledge-plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAiB,MAAM,wBAAwB,CAAC;AAgB3E;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,IAAI,aAAa,CAuCrD"}
+{"version":3,"file":"knowledge-plugin.d.ts","sourceRoot":"","sources":["../src/knowledge-plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAiB,MAAM,wBAAwB,CAAC;AAuB3E;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,IAAI,aAAa,CA6CrD"}

package/dist/knowledge-plugin.js

@@ -8,10 +8,12 @@
  */
 import { grackle } from "@grackle-ai/common";
 import { logger } from "./logger.js";
-import { initKnowledge, neo4jHealthCheck, } from "./knowledge-init.js";
-import { createKnowledgeHealthPhase, markKnowledgeInitFailed } from "./knowledge-health.js";
+import { initKnowledge, neo4jHealthCheck, getKnowledgeEmbedder, } from "./knowledge-init.js";
+import { createKnowledgeHealthPhase, markKnowledgeInitFailed, isNeo4jHealthy, } from "./knowledge-health.js";
+import { createKnowledgeProjectionPhase } from "./knowledge-projection-phase.js";
 import { searchKnowledge, getKnowledgeNode, expandKnowledgeNode, listRecentKnowledgeNodes, } from "./knowledge-handlers.js";
 import { knowledgeMcpTools } from "./mcp-tools.js";
+import { createEntitySyncSubscriber } from "./entity-sync.js";
 /**
  * Create the knowledge plugin that contributes Neo4j-backed knowledge graph
  * read capabilities to the Grackle server. The graph is populated by the
@@ -57,7 +59,12 @@ export function createKnowledgePlugin() {
             }],
         reconciliationPhases: () => [
             createKnowledgeHealthPhase({ healthCheck: neo4jHealthCheck }),
+            createKnowledgeProjectionPhase({
+                getEmbedder: getKnowledgeEmbedder,
+                isHealthy: isNeo4jHealthy,
+            }),
         ],
+        eventSubscribers: (ctx) => [createEntitySyncSubscriber(ctx)],
         mcpTools: () => knowledgeMcpTools,
     };
 }

package/dist/knowledge-plugin.js.map

@@ -1 +1 @@
-{"version":3,"file":"knowledge-plugin.js","sourceRoot":"","sources":["../src/knowledge-plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC7C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EACL,aAAa,EACb,gBAAgB,GACjB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,0BAA0B,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAC5F,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,mBAAmB,EACnB,wBAAwB,GACzB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAEnD;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,qBAAqB;IACnC,IAAI,OAA0C,CAAC;IAE/C,OAAO;QACL,IAAI,EAAE,WAAW;QACjB,YAAY,EAAE,CAAC,MAAM,CAAC;QAEtB,UAAU,EAAE,KAAK,EAAE,GAAkB,EAAiB,EAAE;YACtD,IAAI,CAAC;gBACH,OAAO,GAAG,MAAM,aAAa,CAAC,GAAG,CAAC,CAAC;YACrC,CAAC;YAAC,OAAO,GAAY,EAAE,CAAC;gBACtB,gEAAgE;gBAChE,yEAAyE;gBACzE,uBAAuB,EAAE,CAAC;gBAC1B,MAAM,CAAC,KAAK,CAAC,EAAE,GAAG,EAAE,EAAE,2DAA2D,CAAC,CAAC;YACrF,CAAC;QACH,CAAC;QAED,QAAQ,EAAE,KAAK,IAAmB,EAAE;YAClC,MAAM,OAAO,EAAE,EAAE,CAAC;YAClB,OAAO,GAAG,SAAS,CAAC;QACtB,CAAC;QAED,YAAY,EAAE,GAAG,EAAE,CAAC,CAAC;gBACnB,OAAO,EAAE,OAAO,CAAC,gBAAgB;gBACjC,QAAQ,EAAE;oBACR,eAAe;oBACf,gBAAgB;oBAChB,mBAAmB;oBACnB,wBAAwB;iBACzB;aACF,CAAC;QAEF,oBAAoB,EAAE,GAAG,EAAE,CAAC;YAC1B,0BAA0B,CAAC,EAAE,WAAW,EAAE,gBAAgB,EAAE,CAAC;SAC9D;QAED,QAAQ,EAAE,GAAG,EAAE,CAAC,iBAAiB;KAClC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"knowledge-plugin.js","sourceRoot":"","sources":["../src/knowledge-plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC7C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,0BAA0B,EAC1B,uBAAuB,EACvB,cAAc,GACf,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,8BAA8B,EAAE,MAAM,iCAAiC,CAAC;AACjF,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,mBAAmB,EACnB,wBAAwB,GACzB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAC;AAE9D;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,qBAAqB;IACnC,IAAI,OAA0C,CAAC;IAE/C,OAAO;QACL,IAAI,EAAE,WAAW;QACjB,YAAY,EAAE,CAAC,MAAM,CAAC;QAEtB,UAAU,EAAE,KAAK,EAAE,GAAkB,EAAiB,EAAE;YACtD,IAAI,CAAC;gBACH,OAAO,GAAG,MAAM,aAAa,CAAC,GAAG,CAAC,CAAC;YACrC,CAAC;YAAC,OAAO,GAAY,EAAE,CAAC;gBACtB,gEAAgE;gBAChE,yEAAyE;gBACzE,uBAAuB,EAAE,CAAC;gBAC1B,MAAM,CAAC,KAAK,CAAC,EAAE,GAAG,EAAE,EAAE,2DAA2D,CAAC,CAAC;YACrF,CAAC;QACH,CAAC;QAED,QAAQ,EAAE,KAAK,IAAmB,EAAE;YAClC,MAAM,OAAO,EAAE,EAAE,CAAC;YAClB,OAAO,GAAG,SAAS,CAAC;QACtB,CAAC;QAED,YAAY,EAAE,GAAG,EAAE,CAAC,CAAC;gBACnB,OAAO,EAAE,OAAO,CAAC,gBAAgB;gBACjC,QAAQ,EAAE;oBACR,eAAe;oBACf,gBAAgB;oBAChB,mBAAmB;oBACnB,wBAAwB;iBACzB;aACF,CAAC;QAEF,oBAAoB,EAAE,GAAG,EAAE,CAAC;YAC1B,0BAA0B,CAAC,EAAE,WAAW,EAAE,gBAAgB,EAAE,CAAC;YAC7D,8BAA8B,CAAC;gBAC7B,WAAW,EAAE,oBAAoB;gBACjC,SAAS,EAAE,cAAc;aAC1B,CAAC;SACH;QAED,gBAAgB,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,0BAA0B,CAAC,GAAG,CAAC,CAAC;QAE5D,QAAQ,EAAE,GAAG,EAAE,CAAC,iBAAiB;KAClC,CAAC;AACJ,CAAC"}

package/dist/knowledge-projection-phase.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Reconciliation phase that keeps the derived KG mirror converged (#1258).
+ *
+ * The correctness backbone of the projection. Each tick (gated on Neo4j health
+ * + an available embedder):
+ *   1. **Entity sync** — re-project changed task/workspace/persona/environment
+ *      rows (hash-gated; unchanged rows are skipped) + bulk-prune vanished ones.
+ *   2. **Session sync** — the same for sessions, plus incremental transcript
+ *      chunking (the per-session byte cursor reads at most one bounded window of
+ *      new log content per pass).
+ *   3. **Embed backfill** — embed a bounded batch (`EMBED_BACKFILL_BATCH`) of
+ *      nodes upserted structurally with no embedding (keeps embedding off the
+ *      write path).
+ *
+ * Entity nodes are also projected low-latency by the event subscriber; this
+ * phase guarantees eventual convergence for all (e.g. events missed while Neo4j
+ * was down).
+ *
+ * Bounding: the expensive work is bounded per tick — transcript reads are
+ * byte-capped and embedding is batch-limited. Entity/session reconciliation does
+ * a hash-gated scan of all rows each tick (cheap reads; only changed rows write),
+ * which is acceptable for current entity volumes.
+ *
+ * @module
+ */
+import type { ReconciliationPhase } from "@grackle-ai/plugin-sdk";
+import { type Embedder } from "@grackle-ai/knowledge";
+/** Dependencies for the projection phase (injected for testability). */
+export interface KnowledgeProjectionPhaseDeps {
+    /** Returns the embedder, or undefined when knowledge is not initialized. */
+    getEmbedder: () => Embedder | undefined;
+    /** Returns whether Neo4j is currently reachable. */
+    isHealthy: () => boolean;
+}
+/**
+ * Create the `knowledge-projection` reconciliation phase.
+ */
+export declare function createKnowledgeProjectionPhase(deps: KnowledgeProjectionPhaseDeps): ReconciliationPhase;
+//# sourceMappingURL=knowledge-projection-phase.d.ts.map

package/dist/knowledge-projection-phase.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-projection-phase.d.ts","sourceRoot":"","sources":["../src/knowledge-projection-phase.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AASlE,OAAO,EAOL,KAAK,QAAQ,EAId,MAAM,uBAAuB,CAAC;AA4B/B,wEAAwE;AACxE,MAAM,WAAW,4BAA4B;IAC3C,4EAA4E;IAC5E,WAAW,EAAE,MAAM,QAAQ,GAAG,SAAS,CAAC;IACxC,oDAAoD;IACpD,SAAS,EAAE,MAAM,OAAO,CAAC;CAC1B;AA2GD;;GAEG;AACH,wBAAgB,8BAA8B,CAC5C,IAAI,EAAE,4BAA4B,GACjC,mBAAmB,CAuCrB"}

package/dist/knowledge-projection-phase.js

@@ -0,0 +1,154 @@
+/**
+ * Reconciliation phase that keeps the derived KG mirror converged (#1258).
+ *
+ * The correctness backbone of the projection. Each tick (gated on Neo4j health
+ * + an available embedder):
+ *   1. **Entity sync** — re-project changed task/workspace/persona/environment
+ *      rows (hash-gated; unchanged rows are skipped) + bulk-prune vanished ones.
+ *   2. **Session sync** — the same for sessions, plus incremental transcript
+ *      chunking (the per-session byte cursor reads at most one bounded window of
+ *      new log content per pass).
+ *   3. **Embed backfill** — embed a bounded batch (`EMBED_BACKFILL_BATCH`) of
+ *      nodes upserted structurally with no embedding (keeps embedding off the
+ *      write path).
+ *
+ * Entity nodes are also projected low-latency by the event subscriber; this
+ * phase guarantees eventual convergence for all (e.g. events missed while Neo4j
+ * was down).
+ *
+ * Bounding: the expensive work is bounded per tick — transcript reads are
+ * byte-capped and embedding is batch-limited. Entity/session reconciliation does
+ * a hash-gated scan of all rows each tick (cheap reads; only changed rows write),
+ * which is acceptable for current entity volumes.
+ *
+ * @module
+ */
+import { sessionStore, taskStore, workspaceStore, personaStore, envRegistry, workspaceEnvironmentLinkStore, } from "@grackle-ai/database";
+import { getReferenceNodeProps, listReferenceSourceIds, listNodesMissingEmbedding, updateNode, pruneReferenceNodesNotIn, REFERENCE_SOURCE, } from "@grackle-ai/knowledge";
+import { logger } from "./logger.js";
+import { sessionToNodeInput, environmentToNodeInput, personaToNodeInput, workspaceToNodeInput, taskToNodeInput, } from "./projection/node-mappers.js";
+import { projectSession, linkSessionSpawn, projectEnvironment, projectPersona, projectWorkspace, projectTask, reconcileTaskEdges, reconcileWorkspaceEdges, reconcileSessionEdges, } from "./projection/project-entity.js";
+import { projectSessionTranscript, unprojectSessionTranscript, } from "./projection/project-transcript.js";
+/** Max nodes embedded per tick so CPU-bound embedding never starves the loop. */
+const EMBED_BACKFILL_BATCH = 32;
+/** Text to embed for a node: a reference node's content (chunk) or label, else a native node's content. */
+function embedText(node) {
+    if (node.kind === "reference") {
+        return node.content ?? node.label;
+    }
+    return node.content;
+}
+/** Resolve a session's workspace scope via its task (empty when no task). */
+function resolveSessionWorkspaceId(taskId) {
+    if (!taskId) {
+        return "";
+    }
+    return taskStore.getTask(taskId)?.workspaceId ?? "";
+}
+async function syncSessions(embedder) {
+    const sessions = sessionStore.listSessions();
+    const liveSessionIds = new Set();
+    for (const session of sessions) {
+        liveSessionIds.add(session.id);
+        const workspaceId = resolveSessionWorkspaceId(session.taskId);
+        // Hash-gate the node write, but always reconcile edges: on change re-project
+        // (clears stale + re-applies); when unchanged, re-apply additively so an edge
+        // dropped on an earlier pass (endpoint missing, transient failure) still heals.
+        const desired = sessionToNodeInput(session, workspaceId);
+        const existing = await getReferenceNodeProps(REFERENCE_SOURCE.SESSION, session.id);
+        if (existing?.projectionHash !== desired.extraProps?.projectionHash) {
+            await projectSession(session, workspaceId);
+        }
+        else {
+            await reconcileSessionEdges(session);
+        }
+        // Incremental transcript chunking (cursor-based; cheap when no new content).
+        await projectSessionTranscript(session, embedder);
+    }
+    // SPAWNED edges in a second pass — all session nodes now exist, so a child
+    // projected before its parent still gets its edge (order-independent).
+    for (const session of sessions) {
+        await linkSessionSpawn(session);
+    }
+    // Prune sessions whose row no longer exists, plus their transcript chunks.
+    const existingSessionIds = await listReferenceSourceIds(REFERENCE_SOURCE.SESSION);
+    const vanished = existingSessionIds.filter((id) => !liveSessionIds.has(id));
+    if (vanished.length > 0) {
+        await pruneReferenceNodesNotIn(REFERENCE_SOURCE.SESSION, [...liveSessionIds]);
+        for (const sessionId of vanished) {
+            await unprojectSessionTranscript(sessionId);
+        }
+    }
+}
+/**
+ * Reconcile one reference-node entity type: hash-gated re-project of changed
+ * rows + prune of nodes whose source row no longer exists. This is the
+ * correctness backbone for entities — it converges the mirror even if the
+ * low-latency event subscriber missed an event (e.g. while Neo4j was down).
+ *
+ * @param reconcileEdges - When a row's hash is unchanged (node already current),
+ *   this re-applies its outgoing edges additively (no node write, no stale-clear),
+ *   so an edge dropped on an earlier pass still heals. Omit for edgeless entities.
+ */
+async function syncEntity(sourceType, rows, getId, toInput, project, reconcileEdges) {
+    const liveIds = new Set();
+    for (const row of rows) {
+        const id = getId(row);
+        liveIds.add(id);
+        const existing = await getReferenceNodeProps(sourceType, id);
+        if (existing?.projectionHash !== toInput(row).extraProps?.projectionHash) {
+            await project(row);
+        }
+        else if (reconcileEdges) {
+            await reconcileEdges(row);
+        }
+    }
+    await pruneReferenceNodesNotIn(sourceType, [...liveIds]);
+}
+async function backfillEmbeddings(embedder) {
+    const pending = await listNodesMissingEmbedding(EMBED_BACKFILL_BATCH);
+    for (const node of pending) {
+        const text = embedText(node);
+        if (!text) {
+            continue;
+        }
+        try {
+            const { vector } = await embedder.embed(text);
+            await updateNode(node.id, { embedding: vector });
+        }
+        catch (err) {
+            // Non-fatal: leave the node unembedded; it retries on the next tick.
+            logger.debug({ err, nodeId: node.id }, "Embedding backfill failed; will retry");
+        }
+    }
+}
+/**
+ * Create the `knowledge-projection` reconciliation phase.
+ */
+export function createKnowledgeProjectionPhase(deps) {
+    return {
+        name: "knowledge-projection",
+        execute: async () => {
+            const embedder = deps.getEmbedder();
+            if (!embedder || !deps.isHealthy()) {
+                return;
+            }
+            // Entity backbone (hash-gated): converges the mirror even if the
+            // low-latency event subscriber missed events (e.g. while Neo4j was down).
+            // Endpoints (env/persona/workspace) before tasks/sessions so edges resolve.
+            // Endpointless entities first (env/persona), then workspaces, then tasks/
+            // sessions — so an edge's endpoint node already exists when it is applied.
+            // The `reconcileEdges` arg re-applies edges additively for unchanged rows
+            // each tick, so a transiently-dropped edge eventually heals.
+            await syncEntity(REFERENCE_SOURCE.ENVIRONMENT, envRegistry.listEnvironments(), (row) => row.id, environmentToNodeInput, projectEnvironment);
+            await syncEntity(REFERENCE_SOURCE.PERSONA, personaStore.listPersonas(), (row) => row.id, personaToNodeInput, projectPersona);
+            // Workspace hash folds in the linked-env set so a link/unlink re-projects
+            // (keeps LINKED_TO converged even if the change's event was missed).
+            await syncEntity(REFERENCE_SOURCE.WORKSPACE, workspaceStore.listWorkspaces(), (row) => row.id, (row) => workspaceToNodeInput(row, workspaceEnvironmentLinkStore.getLinkedEnvironmentIds(row.id)), projectWorkspace, reconcileWorkspaceEdges);
+            await syncEntity(REFERENCE_SOURCE.TASK, taskStore.listTasks(), (row) => row.id, taskToNodeInput, projectTask, reconcileTaskEdges);
+            await syncSessions(embedder);
+            await backfillEmbeddings(embedder);
+        },
+    };
+}
+//# sourceMappingURL=knowledge-projection-phase.js.map

package/dist/knowledge-projection-phase.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-projection-phase.js","sourceRoot":"","sources":["../src/knowledge-projection-phase.ts"],"names":[],"mappings":"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"}

package/dist/projection/derive-text.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Pure text derivers that turn a Grackle entity row into an embeddable string
+ * for its knowledge-graph node (#1258).
+ *
+ * Each mirrors the `[Entity] ...` shape of the original task deriver so the
+ * embedding captures the entity's human-meaningful content.
+ *
+ * @module
+ */
+import type { TaskRow, WorkspaceRow, SessionRow, PersonaRow, EnvironmentRow } from "@grackle-ai/database";
+/** Embeddable text for a Task node. */
+export declare function deriveTaskText(task: TaskRow): string;
+/** Embeddable text for a Workspace node. */
+export declare function deriveWorkspaceText(workspace: WorkspaceRow): string;
+/** Embeddable text for a Session node (its prompt is the meaningful content). */
+export declare function deriveSessionText(session: SessionRow): string;
+/** Embeddable text for a Persona node. */
+export declare function derivePersonaText(persona: PersonaRow): string;
+/** Embeddable text for an Environment node. */
+export declare function deriveEnvironmentText(environment: EnvironmentRow): string;
+//# sourceMappingURL=derive-text.d.ts.map

package/dist/projection/derive-text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"derive-text.d.ts","sourceRoot":"","sources":["../../src/projection/derive-text.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EACV,OAAO,EACP,YAAY,EACZ,UAAU,EACV,UAAU,EACV,cAAc,EACf,MAAM,sBAAsB,CAAC;AAO9B,uCAAuC;AACvC,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAEpD;AAED,4CAA4C;AAC5C,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,YAAY,GAAG,MAAM,CAEnE;AAED,iFAAiF;AACjF,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,UAAU,GAAG,MAAM,CAK7D;AAED,0CAA0C;AAC1C,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,UAAU,GAAG,MAAM,CAE7D;AAED,+CAA+C;AAC/C,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,cAAc,GAAG,MAAM,CAKzE"}

package/dist/projection/derive-text.js

@@ -0,0 +1,40 @@
+/**
+ * Pure text derivers that turn a Grackle entity row into an embeddable string
+ * for its knowledge-graph node (#1258).
+ *
+ * Each mirrors the `[Entity] ...` shape of the original task deriver so the
+ * embedding captures the entity's human-meaningful content.
+ *
+ * @module
+ */
+/** Join non-empty parts with " - ". */
+function joinParts(parts) {
+    return parts.filter((part) => Boolean(part && part.trim())).join(" - ");
+}
+/** Embeddable text for a Task node. */
+export function deriveTaskText(task) {
+    return joinParts([`[Task] ${task.title}`, task.description]);
+}
+/** Embeddable text for a Workspace node. */
+export function deriveWorkspaceText(workspace) {
+    return joinParts([`[Workspace] ${workspace.name}`, workspace.description]);
+}
+/** Embeddable text for a Session node (its prompt is the meaningful content). */
+export function deriveSessionText(session) {
+    return joinParts([
+        `[Session] ${session.prompt}`,
+        session.model ? `model:${session.model}` : undefined,
+    ]);
+}
+/** Embeddable text for a Persona node. */
+export function derivePersonaText(persona) {
+    return joinParts([`[Persona] ${persona.name}`, persona.description]);
+}
+/** Embeddable text for an Environment node. */
+export function deriveEnvironmentText(environment) {
+    return joinParts([
+        `[Environment] ${environment.displayName}`,
+        `adapter:${environment.adapterType}`,
+    ]);
+}
+//# sourceMappingURL=derive-text.js.map

package/dist/projection/derive-text.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"derive-text.js","sourceRoot":"","sources":["../../src/projection/derive-text.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAUH,uCAAuC;AACvC,SAAS,SAAS,CAAC,KAAgC;IACjD,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAkB,EAAE,CAAC,OAAO,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAC1F,CAAC;AAED,uCAAuC;AACvC,MAAM,UAAU,cAAc,CAAC,IAAa;IAC1C,OAAO,SAAS,CAAC,CAAC,UAAU,IAAI,CAAC,KAAK,EAAE,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC;AAC/D,CAAC;AAED,4CAA4C;AAC5C,MAAM,UAAU,mBAAmB,CAAC,SAAuB;IACzD,OAAO,SAAS,CAAC,CAAC,eAAe,SAAS,CAAC,IAAI,EAAE,EAAE,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC;AAC7E,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,iBAAiB,CAAC,OAAmB;IACnD,OAAO,SAAS,CAAC;QACf,aAAa,OAAO,CAAC,MAAM,EAAE;QAC7B,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS;KACrD,CAAC,CAAC;AACL,CAAC;AAED,0CAA0C;AAC1C,MAAM,UAAU,iBAAiB,CAAC,OAAmB;IACnD,OAAO,SAAS,CAAC,CAAC,aAAa,OAAO,CAAC,IAAI,EAAE,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC;AACvE,CAAC;AAED,+CAA+C;AAC/C,MAAM,UAAU,qBAAqB,CAAC,WAA2B;IAC/D,OAAO,SAAS,CAAC;QACf,iBAAiB,WAAW,CAAC,WAAW,EAAE;QAC1C,WAAW,WAAW,CAAC,WAAW,EAAE;KACrC,CAAC,CAAC;AACL,CAAC"}

package/dist/projection/edge-mappers.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Pure mappers from Grackle SQL rows to structural knowledge-graph edge specs
+ * (#1258). An {@link EdgeSpec} identifies endpoints by `(sourceType, sourceId)`;
+ * the projector resolves those to node IDs at write time.
+ *
+ * Edge rule: an empty/`""` soft foreign-key reference produces NO edge.
+ *
+ * @module
+ */
+import { type EdgeType, type ReferenceSource } from "@grackle-ai/knowledge";
+import type { TaskRow, SessionRow } from "@grackle-ai/database";
+/** Identifies a reference node by its source identity. */
+export interface SourceKey {
+    sourceType: ReferenceSource;
+    sourceId: string;
+}
+/** A structural edge to project, with endpoints identified by source key. */
+export interface EdgeSpec {
+    from: SourceKey;
+    to: SourceKey;
+    type: EdgeType;
+}
+/** Outgoing structural edge types reconciled on a Task node. */
+export declare const TASK_EDGE_TYPES: EdgeType[];
+/** Outgoing structural edge types reconciled on a Session node. */
+export declare const SESSION_EDGE_TYPES: EdgeType[];
+/** Outgoing structural edge types reconciled on a Workspace node. */
+export declare const WORKSPACE_EDGE_TYPES: EdgeType[];
+/** Defensively parse the `tasks.dependsOn` JSON-array column. */
+export declare function parseDependsOn(raw: string): string[];
+/** Structural edges originating from a Task: IN_WORKSPACE, PART_OF, DEPENDS_ON. */
+export declare function taskEdges(task: TaskRow): EdgeSpec[];
+/** Outgoing structural edges from a Session: ATTEMPT_OF, RAN_IN, USED_PERSONA. */
+export declare function sessionEdges(session: SessionRow): EdgeSpec[];
+/**
+ * The SPAWNED edge (parent Session → this Session). Originates from the parent,
+ * so it is reconciled with the child (parent_session_id is immutable); returned
+ * separately from {@link sessionEdges} and upserted (never bulk-removed) so a
+ * parent's spawn edges aren't cleared when the parent re-projects.
+ */
+export declare function sessionSpawnEdge(session: SessionRow): EdgeSpec | undefined;
+/** The LINKED_TO edge for a workspace↔environment link. */
+export declare function workspaceLinkEdge(workspaceId: string, environmentId: string): EdgeSpec;
+//# sourceMappingURL=edge-mappers.d.ts.map

package/dist/projection/edge-mappers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edge-mappers.d.ts","sourceRoot":"","sources":["../../src/projection/edge-mappers.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAGL,KAAK,QAAQ,EACb,KAAK,eAAe,EACrB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EACV,OAAO,EACP,UAAU,EACX,MAAM,sBAAsB,CAAC;AAE9B,0DAA0D;AAC1D,MAAM,WAAW,SAAS;IACxB,UAAU,EAAE,eAAe,CAAC;IAC5B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,6EAA6E;AAC7E,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,SAAS,CAAC;IAChB,EAAE,EAAE,SAAS,CAAC;IACd,IAAI,EAAE,QAAQ,CAAC;CAChB;AAOD,gEAAgE;AAChE,eAAO,MAAM,eAAe,EAAE,QAAQ,EAIrC,CAAC;AAEF,mEAAmE;AACnE,eAAO,MAAM,kBAAkB,EAAE,QAAQ,EAIxC,CAAC;AAEF,qEAAqE;AACrE,eAAO,MAAM,oBAAoB,EAAE,QAAQ,EAA0B,CAAC;AAEtE,iEAAiE;AACjE,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CASpD;AAED,mFAAmF;AACnF,wBAAgB,SAAS,CAAC,IAAI,EAAE,OAAO,GAAG,QAAQ,EAAE,CAanD;AAED,kFAAkF;AAClF,wBAAgB,YAAY,CAAC,OAAO,EAAE,UAAU,GAAG,QAAQ,EAAE,CAa5D;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,UAAU,GAAG,QAAQ,GAAG,SAAS,CAS1E;AAED,2DAA2D;AAC3D,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,QAAQ,CAMtF"}