@grackle-ai/plugin-knowledge 0.118.0 → 0.120.0

package/dist/projection/edge-mappers.js

@@ -0,0 +1,95 @@
+/**
+ * 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 { EDGE_TYPE, REFERENCE_SOURCE, } from "@grackle-ai/knowledge";
+const key = (sourceType, sourceId) => ({
+    sourceType,
+    sourceId,
+});
+/** Outgoing structural edge types reconciled on a Task node. */
+export const TASK_EDGE_TYPES = [
+    EDGE_TYPE.IN_WORKSPACE,
+    EDGE_TYPE.PART_OF,
+    EDGE_TYPE.DEPENDS_ON,
+];
+/** Outgoing structural edge types reconciled on a Session node. */
+export const SESSION_EDGE_TYPES = [
+    EDGE_TYPE.ATTEMPT_OF,
+    EDGE_TYPE.RAN_IN,
+    EDGE_TYPE.USED_PERSONA,
+];
+/** Outgoing structural edge types reconciled on a Workspace node. */
+export const WORKSPACE_EDGE_TYPES = [EDGE_TYPE.LINKED_TO];
+/** Defensively parse the `tasks.dependsOn` JSON-array column. */
+export function parseDependsOn(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed)
+            ? parsed.filter((item) => typeof item === "string" && item.length > 0)
+            : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** Structural edges originating from a Task: IN_WORKSPACE, PART_OF, DEPENDS_ON. */
+export function taskEdges(task) {
+    const from = key(REFERENCE_SOURCE.TASK, task.id);
+    const edges = [];
+    if (task.workspaceId) {
+        edges.push({ from, to: key(REFERENCE_SOURCE.WORKSPACE, task.workspaceId), type: EDGE_TYPE.IN_WORKSPACE });
+    }
+    if (task.parentTaskId) {
+        edges.push({ from, to: key(REFERENCE_SOURCE.TASK, task.parentTaskId), type: EDGE_TYPE.PART_OF });
+    }
+    for (const dependencyId of parseDependsOn(task.dependsOn)) {
+        edges.push({ from, to: key(REFERENCE_SOURCE.TASK, dependencyId), type: EDGE_TYPE.DEPENDS_ON });
+    }
+    return edges;
+}
+/** Outgoing structural edges from a Session: ATTEMPT_OF, RAN_IN, USED_PERSONA. */
+export function sessionEdges(session) {
+    const from = key(REFERENCE_SOURCE.SESSION, session.id);
+    const edges = [];
+    if (session.taskId) {
+        edges.push({ from, to: key(REFERENCE_SOURCE.TASK, session.taskId), type: EDGE_TYPE.ATTEMPT_OF });
+    }
+    if (session.environmentId) {
+        edges.push({ from, to: key(REFERENCE_SOURCE.ENVIRONMENT, session.environmentId), type: EDGE_TYPE.RAN_IN });
+    }
+    if (session.personaId) {
+        edges.push({ from, to: key(REFERENCE_SOURCE.PERSONA, session.personaId), type: EDGE_TYPE.USED_PERSONA });
+    }
+    return edges;
+}
+/**
+ * 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 function sessionSpawnEdge(session) {
+    if (!session.parentSessionId) {
+        return undefined;
+    }
+    return {
+        from: key(REFERENCE_SOURCE.SESSION, session.parentSessionId),
+        to: key(REFERENCE_SOURCE.SESSION, session.id),
+        type: EDGE_TYPE.SPAWNED,
+    };
+}
+/** The LINKED_TO edge for a workspace↔environment link. */
+export function workspaceLinkEdge(workspaceId, environmentId) {
+    return {
+        from: key(REFERENCE_SOURCE.WORKSPACE, workspaceId),
+        to: key(REFERENCE_SOURCE.ENVIRONMENT, environmentId),
+        type: EDGE_TYPE.LINKED_TO,
+    };
+}
+//# sourceMappingURL=edge-mappers.js.map

package/dist/projection/edge-mappers.js.map

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

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

@@ -0,0 +1,42 @@
+/**
+ * Pure mappers from Grackle SQL rows to knowledge-graph reference-node upsert
+ * inputs (#1258), plus a cheap change-detection hash.
+ *
+ * Kept pure (no IO) so they are unit-testable without Neo4j.
+ *
+ * @module
+ */
+import { type UpsertReferenceNodeInput } from "@grackle-ai/knowledge";
+import type { TaskRow, WorkspaceRow, SessionRow, PersonaRow, EnvironmentRow } from "@grackle-ai/database";
+/**
+ * Stable hash of the projected fields, stored on the node as `projectionHash`
+ * so the reconciliation scan can skip rows whose projection is unchanged.
+ *
+ * Non-cryptographic use (change detection only); SHA-256 is used purely to keep
+ * static analysis happy — no weak-algorithm dependence.
+ */
+export declare function computeProjectionHash(...parts: unknown[]): string;
+/** Map a Task row to its reference-node upsert input. */
+export declare function taskToNodeInput(task: TaskRow): UpsertReferenceNodeInput;
+/**
+ * Map a Workspace row to its reference-node upsert input.
+ *
+ * @param linkedEnvironmentIds - IDs of the environments linked to this workspace
+ *   (the `LINKED_TO` edge set). Folded into the projection hash so a link/unlink
+ *   changes the hash and the reconciliation scan re-projects the workspace,
+ *   keeping `LINKED_TO` edges converged even if the change's event was missed
+ *   (e.g. while Neo4j was down).
+ */
+export declare function workspaceToNodeInput(workspace: WorkspaceRow, linkedEnvironmentIds?: string[]): UpsertReferenceNodeInput;
+/**
+ * Map a Session row to its reference-node upsert input.
+ *
+ * @param workspaceId - Resolved from the session's task (sessions have no direct
+ *   workspace column); empty string when the session has no task.
+ */
+export declare function sessionToNodeInput(session: SessionRow, workspaceId: string): UpsertReferenceNodeInput;
+/** Map a Persona row to its reference-node upsert input (global scope). */
+export declare function personaToNodeInput(persona: PersonaRow): UpsertReferenceNodeInput;
+/** Map an Environment row to its reference-node upsert input (global scope). */
+export declare function environmentToNodeInput(environment: EnvironmentRow): UpsertReferenceNodeInput;
+//# sourceMappingURL=node-mappers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"node-mappers.d.ts","sourceRoot":"","sources":["../../src/projection/node-mappers.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAoB,KAAK,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AACxF,OAAO,KAAK,EACV,OAAO,EACP,YAAY,EACZ,UAAU,EACV,UAAU,EACV,cAAc,EACf,MAAM,sBAAsB,CAAC;AAS9B;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,KAAK,EAAE,OAAO,EAAE,GAAG,MAAM,CAEjE;AAED,yDAAyD;AACzD,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG,wBAAwB,CAoBvE;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,YAAY,EACvB,oBAAoB,GAAE,MAAM,EAAO,GAClC,wBAAwB,CAoB1B;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,UAAU,EACnB,WAAW,EAAE,MAAM,GAClB,wBAAwB,CAqB1B;AAED,2EAA2E;AAC3E,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,UAAU,GAAG,wBAAwB,CAShF;AAED,gFAAgF;AAChF,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,cAAc,GAC1B,wBAAwB,CAY1B"}

package/dist/projection/node-mappers.js

@@ -0,0 +1,106 @@
+/**
+ * Pure mappers from Grackle SQL rows to knowledge-graph reference-node upsert
+ * inputs (#1258), plus a cheap change-detection hash.
+ *
+ * Kept pure (no IO) so they are unit-testable without Neo4j.
+ *
+ * @module
+ */
+import { createHash } from "node:crypto";
+import { REFERENCE_SOURCE } from "@grackle-ai/knowledge";
+import { deriveTaskText, deriveWorkspaceText, deriveSessionText, derivePersonaText, deriveEnvironmentText, } from "./derive-text.js";
+/**
+ * Stable hash of the projected fields, stored on the node as `projectionHash`
+ * so the reconciliation scan can skip rows whose projection is unchanged.
+ *
+ * Non-cryptographic use (change detection only); SHA-256 is used purely to keep
+ * static analysis happy — no weak-algorithm dependence.
+ */
+export function computeProjectionHash(...parts) {
+    return createHash("sha256").update(JSON.stringify(parts)).digest("hex");
+}
+/** Map a Task row to its reference-node upsert input. */
+export function taskToNodeInput(task) {
+    const label = deriveTaskText(task);
+    const workspaceId = task.workspaceId ?? "";
+    return {
+        sourceType: REFERENCE_SOURCE.TASK,
+        sourceId: task.id,
+        label,
+        workspaceId,
+        extraProps: {
+            status: task.status,
+            projectionHash: computeProjectionHash("task", label, workspaceId, task.parentTaskId, task.dependsOn, task.status),
+        },
+    };
+}
+/**
+ * Map a Workspace row to its reference-node upsert input.
+ *
+ * @param linkedEnvironmentIds - IDs of the environments linked to this workspace
+ *   (the `LINKED_TO` edge set). Folded into the projection hash so a link/unlink
+ *   changes the hash and the reconciliation scan re-projects the workspace,
+ *   keeping `LINKED_TO` edges converged even if the change's event was missed
+ *   (e.g. while Neo4j was down).
+ */
+export function workspaceToNodeInput(workspace, linkedEnvironmentIds = []) {
+    const label = deriveWorkspaceText(workspace);
+    return {
+        sourceType: REFERENCE_SOURCE.WORKSPACE,
+        sourceId: workspace.id,
+        label,
+        // A workspace's own scope is itself.
+        workspaceId: workspace.id,
+        extraProps: {
+            status: workspace.status,
+            // Sort so the hash is order-independent (the link store's order is not
+            // guaranteed) and only changes when the link *set* actually changes.
+            projectionHash: computeProjectionHash("workspace", label, workspace.status, [...linkedEnvironmentIds].sort()),
+        },
+    };
+}
+/**
+ * Map a Session row to its reference-node upsert input.
+ *
+ * @param workspaceId - Resolved from the session's task (sessions have no direct
+ *   workspace column); empty string when the session has no task.
+ */
+export function sessionToNodeInput(session, workspaceId) {
+    const label = deriveSessionText(session);
+    return {
+        sourceType: REFERENCE_SOURCE.SESSION,
+        sourceId: session.id,
+        label,
+        workspaceId,
+        extraProps: {
+            status: session.status,
+            projectionHash: computeProjectionHash("session", label, workspaceId, session.taskId, session.environmentId, session.personaId, session.parentSessionId, session.status),
+        },
+    };
+}
+/** Map a Persona row to its reference-node upsert input (global scope). */
+export function personaToNodeInput(persona) {
+    const label = derivePersonaText(persona);
+    return {
+        sourceType: REFERENCE_SOURCE.PERSONA,
+        sourceId: persona.id,
+        label,
+        workspaceId: "",
+        extraProps: { projectionHash: computeProjectionHash("persona", label) },
+    };
+}
+/** Map an Environment row to its reference-node upsert input (global scope). */
+export function environmentToNodeInput(environment) {
+    const label = deriveEnvironmentText(environment);
+    return {
+        sourceType: REFERENCE_SOURCE.ENVIRONMENT,
+        sourceId: environment.id,
+        label,
+        workspaceId: "",
+        extraProps: {
+            status: environment.status,
+            projectionHash: computeProjectionHash("environment", label, environment.status),
+        },
+    };
+}
+//# sourceMappingURL=node-mappers.js.map

package/dist/projection/node-mappers.js.map

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

package/dist/projection/project-entity.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Project a single Grackle entity into the knowledge graph (#1258): upsert its
+ * reference node and reconcile its structural edges. Used by both the
+ * incremental event subscriber and the full rebuild.
+ *
+ * @module
+ */
+import type { TaskRow, WorkspaceRow, SessionRow, PersonaRow, EnvironmentRow } from "@grackle-ai/database";
+/** Project a Task node + reconcile its IN_WORKSPACE / PART_OF / DEPENDS_ON edges (clearing stale). */
+export declare function projectTask(task: TaskRow): Promise<void>;
+/** Project a Workspace node + reconcile its LINKED_TO edges (clearing stale). */
+export declare function projectWorkspace(workspace: WorkspaceRow): Promise<void>;
+/**
+ * Project a Session node + reconcile its ATTEMPT_OF / RAN_IN / USED_PERSONA edges
+ * (clearing stale). The incoming SPAWNED edge is handled by {@link linkSessionSpawn}.
+ *
+ * @param workspaceId - Resolved from the session's task (empty if none).
+ */
+export declare function projectSession(session: SessionRow, workspaceId: string): Promise<void>;
+/**
+ * Re-apply an entity's outgoing edges with `MERGE` **without** clearing stale ones
+ * (additive). Used by the reconciliation scan for rows whose hash is unchanged, so
+ * any edge previously dropped (endpoint projected later, or a transient failure) is
+ * eventually healed. A no-op if the node is not projected yet (the next pass or a
+ * rebuild closes the gap once it exists).
+ */
+export declare function reconcileTaskEdges(task: TaskRow): Promise<void>;
+/** Additive re-apply of a Workspace's LINKED_TO edges (see {@link reconcileTaskEdges}). */
+export declare function reconcileWorkspaceEdges(workspace: WorkspaceRow): Promise<void>;
+/** Additive re-apply of a Session's outgoing edges (see {@link reconcileTaskEdges}). */
+export declare function reconcileSessionEdges(session: SessionRow): Promise<void>;
+/**
+ * Upsert the incoming SPAWNED edge (parent session → this session), if any.
+ *
+ * Run as a separate pass *after* all session nodes exist so that ordering
+ * (e.g. a child projected before its parent) never permanently drops the edge.
+ * Idempotent (MERGE), so it is safe to call every pass.
+ */
+export declare function linkSessionSpawn(session: SessionRow): Promise<void>;
+/** Project a Persona node (no outgoing structural edges). */
+export declare function projectPersona(persona: PersonaRow): Promise<void>;
+/** Project an Environment node (no outgoing structural edges). */
+export declare function projectEnvironment(environment: EnvironmentRow): Promise<void>;
+/** Remove a Task node and its edges. */
+export declare function unprojectTask(id: string): Promise<void>;
+/** Remove a Workspace node and its edges. */
+export declare function unprojectWorkspace(id: string): Promise<void>;
+/** Remove a Session node and its edges. */
+export declare function unprojectSession(id: string): Promise<void>;
+/** Remove a Persona node and its edges. */
+export declare function unprojectPersona(id: string): Promise<void>;
+/** Remove an Environment node and its edges. */
+export declare function unprojectEnvironment(id: string): Promise<void>;
+//# sourceMappingURL=project-entity.d.ts.map

package/dist/projection/project-entity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-entity.d.ts","sourceRoot":"","sources":["../../src/projection/project-entity.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAeH,OAAO,KAAK,EACV,OAAO,EACP,YAAY,EACZ,UAAU,EACV,UAAU,EACV,cAAc,EACf,MAAM,sBAAsB,CAAC;AA0F9B,sGAAsG;AACtG,wBAAsB,WAAW,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAG9D;AAED,iFAAiF;AACjF,wBAAsB,gBAAgB,CAAC,SAAS,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAO7E;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAG5F;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAKrE;AAED,2FAA2F;AAC3F,wBAAsB,uBAAuB,CAAC,SAAS,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAKpF;AAED,wFAAwF;AACxF,wBAAsB,qBAAqB,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAK9E;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAKzE;AAED,6DAA6D;AAC7D,wBAAsB,cAAc,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAEvE;AAED,kEAAkE;AAClE,wBAAsB,kBAAkB,CAAC,WAAW,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAEnF;AAED,wCAAwC;AACxC,wBAAsB,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE7D;AAED,6CAA6C;AAC7C,wBAAsB,kBAAkB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAElE;AAED,2CAA2C;AAC3C,wBAAsB,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEhE;AAED,2CAA2C;AAC3C,wBAAsB,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEhE;AAED,gDAAgD;AAChD,wBAAsB,oBAAoB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEpE"}

package/dist/projection/project-entity.js

@@ -0,0 +1,164 @@
+/**
+ * Project a single Grackle entity into the knowledge graph (#1258): upsert its
+ * reference node and reconcile its structural edges. Used by both the
+ * incremental event subscriber and the full rebuild.
+ *
+ * @module
+ */
+import { upsertReferenceNode, upsertEdge, removeOutgoingEdges, findReferenceNodeBySource, getReferenceNodeProps, updateNode, deleteReferenceNodeBySource, REFERENCE_SOURCE, } from "@grackle-ai/knowledge";
+import { workspaceEnvironmentLinkStore } from "@grackle-ai/database";
+import { taskToNodeInput, workspaceToNodeInput, sessionToNodeInput, personaToNodeInput, environmentToNodeInput, } from "./node-mappers.js";
+import { taskEdges, sessionEdges, sessionSpawnEdge, workspaceLinkEdge, TASK_EDGE_TYPES, SESSION_EDGE_TYPES, WORKSPACE_EDGE_TYPES, } from "./edge-mappers.js";
+/**
+ * Resolve both endpoints of an edge spec and upsert the edge. Returns `false`
+ * (a no-op) if either endpoint node is not projected yet — the next tick or a
+ * rebuild will close the gap once both nodes exist.
+ */
+async function applyEdge(spec) {
+    const [from, to] = await Promise.all([
+        findReferenceNodeBySource(spec.from.sourceType, spec.from.sourceId),
+        findReferenceNodeBySource(spec.to.sourceType, spec.to.sourceId),
+    ]);
+    if (!from || !to) {
+        return false;
+    }
+    await upsertEdge(from.id, to.id, spec.type);
+    return true;
+}
+/**
+ * Upsert an entity reference node and, when its projected text changed, clear the
+ * stale embedding so the off-write-path backfill recomputes it.
+ *
+ * `upsertReferenceNode` sets the embedding only on create, so a re-projection
+ * (e.g. a changed task title, persona prompt/model, or workspace scope) would
+ * otherwise keep the old vector and leave semantic search stale. We detect the
+ * change via the `projectionHash` (compared to the stored one) and reset the
+ * embedding to `[]`; new nodes already start empty. Centralized here so every
+ * caller (event subscriber, reconciliation scan, rebuild) stays consistent.
+ *
+ * @returns The (stable) node ID.
+ */
+async function upsertEntityNode(input) {
+    const newHash = input.extraProps?.projectionHash;
+    const existing = await getReferenceNodeProps(input.sourceType, input.sourceId);
+    const nodeId = await upsertReferenceNode(input);
+    if (existing && newHash !== undefined && existing.projectionHash !== newHash) {
+        await updateNode(nodeId, { embedding: [] });
+    }
+    return nodeId;
+}
+/**
+ * Reconcile a node's outgoing structural edges.
+ *
+ * Always (re-)applies the current edge set with `MERGE` (idempotent + additive),
+ * so an edge that was skipped on an earlier pass because an endpoint node did not
+ * exist yet is healed on a later pass — even when the node's projection hash is
+ * unchanged. `removeOutgoingEdges` (clearing stale edges, e.g. from a changed
+ * foreign key) runs **only** when `clearStale` is set, i.e. when the projection
+ * actually changed; an unchanged re-apply must never bulk-remove.
+ */
+async function reconcileEdges(nodeId, types, specs, clearStale) {
+    if (clearStale) {
+        await removeOutgoingEdges(nodeId, types);
+    }
+    for (const spec of specs) {
+        await applyEdge(spec);
+    }
+}
+/** Resolve a workspace's LINKED_TO edge specs from the junction table. */
+function workspaceLinkEdges(workspaceId) {
+    return workspaceEnvironmentLinkStore
+        .getLinkedEnvironmentIds(workspaceId)
+        .map((environmentId) => workspaceLinkEdge(workspaceId, environmentId));
+}
+/** Project a Task node + reconcile its IN_WORKSPACE / PART_OF / DEPENDS_ON edges (clearing stale). */
+export async function projectTask(task) {
+    const nodeId = await upsertEntityNode(taskToNodeInput(task));
+    await reconcileEdges(nodeId, TASK_EDGE_TYPES, taskEdges(task), true);
+}
+/** Project a Workspace node + reconcile its LINKED_TO edges (clearing stale). */
+export async function projectWorkspace(workspace) {
+    // The link set feeds the projection hash (so link changes trigger re-project)
+    // and the LINKED_TO edge reconciliation below.
+    const nodeId = await upsertEntityNode(workspaceToNodeInput(workspace, workspaceEnvironmentLinkStore.getLinkedEnvironmentIds(workspace.id)));
+    await reconcileEdges(nodeId, WORKSPACE_EDGE_TYPES, workspaceLinkEdges(workspace.id), true);
+}
+/**
+ * Project a Session node + reconcile its ATTEMPT_OF / RAN_IN / USED_PERSONA edges
+ * (clearing stale). The incoming SPAWNED edge is handled by {@link linkSessionSpawn}.
+ *
+ * @param workspaceId - Resolved from the session's task (empty if none).
+ */
+export async function projectSession(session, workspaceId) {
+    const nodeId = await upsertEntityNode(sessionToNodeInput(session, workspaceId));
+    await reconcileEdges(nodeId, SESSION_EDGE_TYPES, sessionEdges(session), true);
+}
+/**
+ * Re-apply an entity's outgoing edges with `MERGE` **without** clearing stale ones
+ * (additive). Used by the reconciliation scan for rows whose hash is unchanged, so
+ * any edge previously dropped (endpoint projected later, or a transient failure) is
+ * eventually healed. A no-op if the node is not projected yet (the next pass or a
+ * rebuild closes the gap once it exists).
+ */
+export async function reconcileTaskEdges(task) {
+    const node = await findReferenceNodeBySource(REFERENCE_SOURCE.TASK, task.id);
+    if (node) {
+        await reconcileEdges(node.id, TASK_EDGE_TYPES, taskEdges(task), false);
+    }
+}
+/** Additive re-apply of a Workspace's LINKED_TO edges (see {@link reconcileTaskEdges}). */
+export async function reconcileWorkspaceEdges(workspace) {
+    const node = await findReferenceNodeBySource(REFERENCE_SOURCE.WORKSPACE, workspace.id);
+    if (node) {
+        await reconcileEdges(node.id, WORKSPACE_EDGE_TYPES, workspaceLinkEdges(workspace.id), false);
+    }
+}
+/** Additive re-apply of a Session's outgoing edges (see {@link reconcileTaskEdges}). */
+export async function reconcileSessionEdges(session) {
+    const node = await findReferenceNodeBySource(REFERENCE_SOURCE.SESSION, session.id);
+    if (node) {
+        await reconcileEdges(node.id, SESSION_EDGE_TYPES, sessionEdges(session), false);
+    }
+}
+/**
+ * Upsert the incoming SPAWNED edge (parent session → this session), if any.
+ *
+ * Run as a separate pass *after* all session nodes exist so that ordering
+ * (e.g. a child projected before its parent) never permanently drops the edge.
+ * Idempotent (MERGE), so it is safe to call every pass.
+ */
+export async function linkSessionSpawn(session) {
+    const spawn = sessionSpawnEdge(session);
+    if (spawn) {
+        await applyEdge(spawn);
+    }
+}
+/** Project a Persona node (no outgoing structural edges). */
+export async function projectPersona(persona) {
+    await upsertEntityNode(personaToNodeInput(persona));
+}
+/** Project an Environment node (no outgoing structural edges). */
+export async function projectEnvironment(environment) {
+    await upsertEntityNode(environmentToNodeInput(environment));
+}
+/** Remove a Task node and its edges. */
+export async function unprojectTask(id) {
+    await deleteReferenceNodeBySource(REFERENCE_SOURCE.TASK, id);
+}
+/** Remove a Workspace node and its edges. */
+export async function unprojectWorkspace(id) {
+    await deleteReferenceNodeBySource(REFERENCE_SOURCE.WORKSPACE, id);
+}
+/** Remove a Session node and its edges. */
+export async function unprojectSession(id) {
+    await deleteReferenceNodeBySource(REFERENCE_SOURCE.SESSION, id);
+}
+/** Remove a Persona node and its edges. */
+export async function unprojectPersona(id) {
+    await deleteReferenceNodeBySource(REFERENCE_SOURCE.PERSONA, id);
+}
+/** Remove an Environment node and its edges. */
+export async function unprojectEnvironment(id) {
+    await deleteReferenceNodeBySource(REFERENCE_SOURCE.ENVIRONMENT, id);
+}
+//# sourceMappingURL=project-entity.js.map

package/dist/projection/project-entity.js.map

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

package/dist/projection/project-transcript.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Incrementally project a session's transcript log into TranscriptChunk nodes
+ * (#1258).
+ *
+ * Uses a per-session byte-offset cursor (`logByteOffset`, with `chunkCount`)
+ * stored on the Session node so each pass reads + chunks + embeds **only new
+ * log content** since the last pass — O(new bytes), never re-reading the whole
+ * transcript. New chunks are appended as reference nodes (`transcript_chunk`)
+ * with a `PART_OF` edge to the session. The chunk text is re-derivable from the
+ * log, so the keystone holds.
+ *
+ * @module
+ */
+import { type Embedder } from "@grackle-ai/knowledge";
+import type { SessionRow } from "@grackle-ai/database";
+/**
+ * Project new transcript content for one session.
+ *
+ * @returns The number of new chunk nodes created this pass.
+ */
+export declare function projectSessionTranscript(session: SessionRow, embedder: Embedder): Promise<number>;
+/**
+ * Delete all transcript-chunk nodes for a session. Used when a session is
+ * pruned (its node's `DETACH DELETE` does not remove the separate chunk nodes).
+ *
+ * @returns The number of chunk nodes removed.
+ */
+export declare function unprojectSessionTranscript(sessionId: string): Promise<number>;
+//# sourceMappingURL=project-transcript.d.ts.map

package/dist/projection/project-transcript.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-transcript.d.ts","sourceRoot":"","sources":["../../src/projection/project-transcript.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EASL,KAAK,QAAQ,EACd,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAKvD;;;;GAIG;AACH,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,UAAU,EACnB,QAAQ,EAAE,QAAQ,GACjB,OAAO,CAAC,MAAM,CAAC,CAiEjB;AAED;;;;;GAKG;AACH,wBAAsB,0BAA0B,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAEnF"}

package/dist/projection/project-transcript.js

@@ -0,0 +1,90 @@
+/**
+ * Incrementally project a session's transcript log into TranscriptChunk nodes
+ * (#1258).
+ *
+ * Uses a per-session byte-offset cursor (`logByteOffset`, with `chunkCount`)
+ * stored on the Session node so each pass reads + chunks + embeds **only new
+ * log content** since the last pass — O(new bytes), never re-reading the whole
+ * transcript. New chunks are appended as reference nodes (`transcript_chunk`)
+ * with a `PART_OF` edge to the session. The chunk text is re-derivable from the
+ * log, so the keystone holds.
+ *
+ * @module
+ */
+import { logWriter } from "@grackle-ai/core";
+import { createTranscriptChunker, ingest, getReferenceNodeProps, upsertReferenceNode, upsertEdge, deleteReferenceNodesByPrefix, REFERENCE_SOURCE, EDGE_TYPE, } from "@grackle-ai/knowledge";
+/** Max characters of chunk text kept in the node `label` (a short preview). */
+const CHUNK_PREVIEW_LENGTH = 120;
+/**
+ * Project new transcript content for one session.
+ *
+ * @returns The number of new chunk nodes created this pass.
+ */
+export async function projectSessionTranscript(session, embedder) {
+    if (!session.logPath) {
+        return 0;
+    }
+    // The Session node must already be projected (it carries the cursor + scope).
+    const sessionProps = await getReferenceNodeProps(REFERENCE_SOURCE.SESSION, session.id);
+    if (!sessionProps) {
+        return 0;
+    }
+    const sessionNodeId = sessionProps.id;
+    const sessionWorkspaceId = sessionProps.workspaceId ?? "";
+    const byteOffset = typeof sessionProps.logByteOffset === "number" ? sessionProps.logByteOffset : 0;
+    let chunkCount = typeof sessionProps.chunkCount === "number" ? sessionProps.chunkCount : 0;
+    // Read only the bytes appended since the last pass (O(new bytes), not O(log)).
+    const { content: newContent, nextOffset } = logWriter.readLogFrom(session.logPath, byteOffset);
+    // Truncation/rewrite: the log shrank below our cursor, so `readLogFrom` reset
+    // to offset 0. Clear the stale chunk nodes and reset the chunk index so the
+    // re-ingestion from the start neither collides with nor strands old chunks.
+    const truncated = nextOffset < byteOffset;
+    if (truncated) {
+        await deleteReferenceNodesByPrefix(REFERENCE_SOURCE.TRANSCRIPT_CHUNK, `${session.id}#`);
+        chunkCount = 0;
+    }
+    let created = 0;
+    if (newContent) {
+        const embeddedChunks = await ingest(newContent, createTranscriptChunker(), embedder, {
+            sessionId: session.id,
+        });
+        for (const chunk of embeddedChunks) {
+            const index = chunkCount + chunk.index;
+            const chunkNodeId = await upsertReferenceNode({
+                sourceType: REFERENCE_SOURCE.TRANSCRIPT_CHUNK,
+                sourceId: `${session.id}#${index}`,
+                label: chunk.text.slice(0, CHUNK_PREVIEW_LENGTH),
+                content: chunk.text,
+                workspaceId: sessionWorkspaceId,
+                embedding: chunk.vector,
+            });
+            await upsertEdge(chunkNodeId, sessionNodeId, EDGE_TYPE.PART_OF);
+        }
+        chunkCount += embeddedChunks.length;
+        created = embeddedChunks.length;
+    }
+    // Persist the cursor whenever it moved (or a truncation reset it) — even with
+    // no new chunks. `readLogFrom` can advance past an over-long line that yielded
+    // no complete line this pass; not persisting that would stall the cursor and
+    // re-read the same bytes forever.
+    if (truncated || nextOffset !== byteOffset) {
+        await upsertReferenceNode({
+            sourceType: REFERENCE_SOURCE.SESSION,
+            sourceId: session.id,
+            label: sessionProps.label ?? "",
+            workspaceId: sessionWorkspaceId,
+            extraProps: { logByteOffset: nextOffset, chunkCount },
+        });
+    }
+    return created;
+}
+/**
+ * Delete all transcript-chunk nodes for a session. Used when a session is
+ * pruned (its node's `DETACH DELETE` does not remove the separate chunk nodes).
+ *
+ * @returns The number of chunk nodes removed.
+ */
+export async function unprojectSessionTranscript(sessionId) {
+    return deleteReferenceNodesByPrefix(REFERENCE_SOURCE.TRANSCRIPT_CHUNK, `${sessionId}#`);
+}
+//# sourceMappingURL=project-transcript.js.map

package/dist/projection/project-transcript.js.map

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