@lucern/graph-sync 0.3.0-alpha.10

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+All notable changes to `@lucern/graph-sync` will be documented in this file.
+
+## [Unreleased]
+- No unreleased changes yet.
+
+## [0.3.0-alpha.7] - 2026-05-03
+- Rebuild the coherent Lucern package line after Campaign 1 SDK hardening fixes.
+
+## [0.3.0-alpha.6] - 2026-05-03
+- Promote `@lucern/graph-sync` to a publishable opt-in Neo4j graph mirroring package.
+- Add the host `neo4jEdgeAPI` and query route helper surfaces for tenant Convex and Vercel installs.

package/README.md

@@ -0,0 +1,121 @@
+# @lucern/graph-sync
+
+Optional Neo4j graph mirroring for Lucern tenant Convex hosts.
+
+`@lucern/graph-sync` packages the host-side surface that the reasoning kernel
+expects when graph mirroring is enabled: Neo4j driver access, node/edge sync
+actions, edge topology writes, backfill/health actions, query proxy actions, and
+a small route-handler helper for Vercel/Next API routes.
+
+## Install
+
+```bash
+pnpm add @lucern/graph-sync
+```
+
+Most tenants should install this only after the regular Convex component
+profile is present:
+
+```bash
+pnpm add @lucern/identity @lucern/reasoning-kernel @lucern/graph-sync
+```
+
+## Environment
+
+Required for direct Neo4j sync and edge actions:
+
+- `NEO4J_URI`
+- `NEO4J_USER`
+- `NEO4J_PASSWORD`
+
+Required only when using the HTTP query proxy actions:
+
+- `NEO4J_SYNC_SECRET`
+
+Optional query proxy configuration:
+
+- `LUCERN_GRAPH_SYNC_QUERY_BASE_URL` or `NEXT_PUBLIC_APP_URL`
+- `LUCERN_GRAPH_SYNC_ALLOWED_PROXY_HOSTS`
+- `VERCEL_AUTOMATION_BYPASS_SECRET`
+
+## Convex Host Re-Exports
+
+Tenant Convex hosts opt in explicitly by adding small wrapper files. The package
+does not inject host schema or tables by installing.
+
+```ts
+// convex/neo4jSync.ts
+export * from "@lucern/graph-sync/neo4jSync";
+```
+
+```ts
+// convex/neo4jSyncHelpers.ts
+export * from "@lucern/graph-sync/neo4jSyncHelpers";
+```
+
+```ts
+// convex/neo4jDriver.ts
+export * from "@lucern/graph-sync/neo4jDriver";
+```
+
+```ts
+// convex/neo4jEdgeAPI.ts
+export * from "@lucern/graph-sync/neo4jEdgeAPI";
+```
+
+```ts
+// convex/neo4jQueries.ts
+export * from "@lucern/graph-sync/neo4jQueries";
+```
+
+The host must already expose the reasoning-kernel tables that these actions
+read and mirror, including `epistemicNodes`, `epistemicEdges`,
+`epistemicNodeEmbeddings`, and `neo4jSyncQueue`.
+
+## Query Proxy Route
+
+`neo4jQueries` actions call a tenant-owned HTTP route so Convex can execute
+predefined graph queries through a host app. The route helper accepts named
+queries only; it never accepts raw Cypher from request bodies.
+
+```ts
+// app/api/neo4j-query/route.ts
+import {
+  createNeo4jQueryRouteHandler,
+  type Neo4jQueryRegistry,
+} from "@lucern/graph-sync/neo4jQueryRoute";
+
+const queries = {
+  nodeLineage: {
+    cypher: `
+      MATCH path = (n {globalId: $globalId})-[:EXTRACTED_FROM|BASED_ON*1..10]->(ancestor)
+      RETURN [node in nodes(path) | {
+        globalId: node.globalId,
+        title: node.title,
+        text: node.canonicalText
+      }] as lineage
+      ORDER BY length(path) DESC
+      LIMIT 1
+    `,
+  },
+} satisfies Neo4jQueryRegistry;
+
+export const POST = createNeo4jQueryRouteHandler({ queries });
+```
+
+## Component Safety
+
+This package is an opt-in host add-on. It does not install a Convex component
+and does not mutate the tenant host schema. Any future queue/table requirement
+must be represented in the reasoning-kernel schema contract or documented as an
+explicit tenant host addition before release.
+
+## Public Exports
+
+- `@lucern/graph-sync`
+- `@lucern/graph-sync/neo4jDriver`
+- `@lucern/graph-sync/neo4jEdgeAPI`
+- `@lucern/graph-sync/neo4jQueries`
+- `@lucern/graph-sync/neo4jQueryRoute`
+- `@lucern/graph-sync/neo4jSync`
+- `@lucern/graph-sync/neo4jSyncHelpers`

package/dist/index.d.ts

@@ -0,0 +1,207 @@
+export { n as neo4jQueries } from './neo4jQueries-eF7YNiqS.js';
+export { n as neo4jSyncHelpers } from './neo4jSyncHelpers-vxe1-Gvw.js';
+
+/**
+ * neo4jDriver module implementation.
+ */
+declare function validateLabel(label: string): void;
+declare function validateRelType(relType: string): void;
+/**
+ * Default query timeout in milliseconds.
+ * Prevents expensive graph traversals from hanging indefinitely.
+ */
+declare const DEFAULT_QUERY_TIMEOUT_MS = 30000;
+/**
+ * Timeout for complex graph queries (cascade simulation, lineage traversal)
+ */
+declare const COMPLEX_QUERY_TIMEOUT_MS = 60000;
+/**
+ * Execute a Cypher query and return results as typed objects
+ *
+ * @param query - Cypher query string
+ * @param params - Query parameters
+ * @param timeoutMs - Query timeout in milliseconds (default: 30s)
+ */
+declare function runCypher<T = Record<string, unknown>>(query: string, params?: Record<string, unknown>, timeoutMs?: number): Promise<T[]>;
+/**
+ * Execute a write transaction (for mutations)
+ *
+ * @param query - Cypher query string
+ * @param params - Query parameters
+ * @param timeoutMs - Transaction timeout in milliseconds (default: 30s)
+ */
+declare function runWriteTransaction<T = Record<string, unknown>>(query: string, params?: Record<string, unknown>, timeoutMs?: number): Promise<T[]>;
+/**
+ * Execute multiple queries in a single transaction
+ *
+ * @param queries - Array of queries with parameters
+ * @param timeoutMs - Transaction timeout in milliseconds (default: 60s for batch)
+ */
+declare function runBatchTransaction(queries: Array<{
+    query: string;
+    params: Record<string, unknown>;
+}>, timeoutMs?: number): Promise<void>;
+/**
+ * Upsert a node by globalId
+ */
+declare function upsertNode(label: string, globalId: string, properties: Record<string, unknown>): Promise<void>;
+/**
+ * Delete a node by globalId
+ */
+declare function deleteNode(globalId: string): Promise<void>;
+/**
+ * Batch upsert nodes
+ */
+declare function batchUpsertNodes(label: string, nodes: Array<{
+    globalId: string;
+    properties: Record<string, unknown>;
+}>): Promise<void>;
+/**
+ * Upsert an edge by globalId
+ */
+declare function upsertEdge(relType: string, globalId: string, fromGlobalId: string, toGlobalId: string, properties?: Record<string, unknown>): Promise<void>;
+/**
+ * Delete an edge by globalId
+ */
+declare function deleteEdge$1(globalId: string): Promise<void>;
+/**
+ * Batch upsert edges
+ */
+declare function batchUpsertEdges(edges: Array<{
+    relType: string;
+    globalId: string;
+    fromGlobalId: string;
+    toGlobalId: string;
+    properties?: Record<string, unknown>;
+}>): Promise<void>;
+/**
+ * Check if Neo4j connection is healthy
+ */
+declare function healthCheck(): Promise<{
+    healthy: boolean;
+    nodeCount?: number;
+    error?: string;
+}>;
+/**
+ * Get connection info (for debugging)
+ */
+declare function getConnectionInfo(): {
+    uri: string | undefined;
+    user: string | undefined;
+    configured: boolean;
+};
+/**
+ * Close the driver connection (for graceful shutdown)
+ */
+declare function closeDriver(): Promise<void>;
+
+declare const neo4jDriver_COMPLEX_QUERY_TIMEOUT_MS: typeof COMPLEX_QUERY_TIMEOUT_MS;
+declare const neo4jDriver_DEFAULT_QUERY_TIMEOUT_MS: typeof DEFAULT_QUERY_TIMEOUT_MS;
+declare const neo4jDriver_batchUpsertEdges: typeof batchUpsertEdges;
+declare const neo4jDriver_batchUpsertNodes: typeof batchUpsertNodes;
+declare const neo4jDriver_closeDriver: typeof closeDriver;
+declare const neo4jDriver_deleteNode: typeof deleteNode;
+declare const neo4jDriver_getConnectionInfo: typeof getConnectionInfo;
+declare const neo4jDriver_healthCheck: typeof healthCheck;
+declare const neo4jDriver_runBatchTransaction: typeof runBatchTransaction;
+declare const neo4jDriver_runCypher: typeof runCypher;
+declare const neo4jDriver_runWriteTransaction: typeof runWriteTransaction;
+declare const neo4jDriver_upsertEdge: typeof upsertEdge;
+declare const neo4jDriver_upsertNode: typeof upsertNode;
+declare const neo4jDriver_validateLabel: typeof validateLabel;
+declare const neo4jDriver_validateRelType: typeof validateRelType;
+declare namespace neo4jDriver {
+  export { neo4jDriver_COMPLEX_QUERY_TIMEOUT_MS as COMPLEX_QUERY_TIMEOUT_MS, neo4jDriver_DEFAULT_QUERY_TIMEOUT_MS as DEFAULT_QUERY_TIMEOUT_MS, neo4jDriver_batchUpsertEdges as batchUpsertEdges, neo4jDriver_batchUpsertNodes as batchUpsertNodes, neo4jDriver_closeDriver as closeDriver, deleteEdge$1 as deleteEdge, neo4jDriver_deleteNode as deleteNode, neo4jDriver_getConnectionInfo as getConnectionInfo, neo4jDriver_healthCheck as healthCheck, neo4jDriver_runBatchTransaction as runBatchTransaction, neo4jDriver_runCypher as runCypher, neo4jDriver_runWriteTransaction as runWriteTransaction, neo4jDriver_upsertEdge as upsertEdge, neo4jDriver_upsertNode as upsertNode, neo4jDriver_validateLabel as validateLabel, neo4jDriver_validateRelType as validateRelType };
+}
+
+declare const DUAL_WRITE_EDGE_TYPES: readonly ["supports", "informs", "tests", "depends_on", "derived_from", "contains", "supersedes", "extracted_from", "responds_to", "based_on", "answers", "belongs_to", "relates_to_thesis", "corroborates", "extends", "same_source_as", "same_theme_as", "plays_theme", "impacts", "evaluates", "mentioned_in", "perspective_on"];
+type DualWriteEdgeType = (typeof DUAL_WRITE_EDGE_TYPES)[number];
+declare function needsDualWrite(edgeType: string): boolean;
+declare const createEdge: any;
+declare const deleteEdge: any;
+declare const updateEdge: any;
+declare const getEdge: any;
+declare const retryProjectionByGlobalId: any;
+
+declare const neo4jEdgeAPI_DUAL_WRITE_EDGE_TYPES: typeof DUAL_WRITE_EDGE_TYPES;
+type neo4jEdgeAPI_DualWriteEdgeType = DualWriteEdgeType;
+declare const neo4jEdgeAPI_createEdge: typeof createEdge;
+declare const neo4jEdgeAPI_deleteEdge: typeof deleteEdge;
+declare const neo4jEdgeAPI_getEdge: typeof getEdge;
+declare const neo4jEdgeAPI_needsDualWrite: typeof needsDualWrite;
+declare const neo4jEdgeAPI_retryProjectionByGlobalId: typeof retryProjectionByGlobalId;
+declare const neo4jEdgeAPI_updateEdge: typeof updateEdge;
+declare namespace neo4jEdgeAPI {
+  export { neo4jEdgeAPI_DUAL_WRITE_EDGE_TYPES as DUAL_WRITE_EDGE_TYPES, type neo4jEdgeAPI_DualWriteEdgeType as DualWriteEdgeType, neo4jEdgeAPI_createEdge as createEdge, neo4jEdgeAPI_deleteEdge as deleteEdge, neo4jEdgeAPI_getEdge as getEdge, neo4jEdgeAPI_needsDualWrite as needsDualWrite, neo4jEdgeAPI_retryProjectionByGlobalId as retryProjectionByGlobalId, neo4jEdgeAPI_updateEdge as updateEdge };
+}
+
+/**
+ * Vercel/Next route helper for the Neo4j query proxy.
+ *
+ * The helper accepts named Cypher only. It never accepts raw Cypher from a
+ * request body, which keeps tenant routes small without opening an injection
+ * surface.
+ */
+type Neo4jNamedQuery = Readonly<{
+    cypher: string;
+    timeoutMs?: number;
+}>;
+type Neo4jQueryRegistry = Readonly<Record<string, Neo4jNamedQuery>>;
+type Neo4jQueryRouteOptions = Readonly<{
+    queries: Neo4jQueryRegistry;
+    syncSecret?: string;
+    requireTenantContext?: boolean;
+}>;
+declare function createNeo4jQueryRouteHandler(options: Neo4jQueryRouteOptions): (request: Request) => Promise<Response>;
+
+type neo4jQueryRoute_Neo4jNamedQuery = Neo4jNamedQuery;
+type neo4jQueryRoute_Neo4jQueryRegistry = Neo4jQueryRegistry;
+type neo4jQueryRoute_Neo4jQueryRouteOptions = Neo4jQueryRouteOptions;
+declare const neo4jQueryRoute_createNeo4jQueryRouteHandler: typeof createNeo4jQueryRouteHandler;
+declare namespace neo4jQueryRoute {
+  export { type neo4jQueryRoute_Neo4jNamedQuery as Neo4jNamedQuery, type neo4jQueryRoute_Neo4jQueryRegistry as Neo4jQueryRegistry, type neo4jQueryRoute_Neo4jQueryRouteOptions as Neo4jQueryRouteOptions, neo4jQueryRoute_createNeo4jQueryRouteHandler as createNeo4jQueryRouteHandler };
+}
+
+/**
+ * neo4jSync module implementation.
+ */
+declare const syncNodeToNeo4j: any;
+declare const syncEdgeToNeo4j: any;
+declare const syncAllNodesToNeo4j: any;
+declare const syncAllEdgesToNeo4j: any;
+declare const backfillAllToNeo4j: any;
+declare const processRetryQueue: any;
+/**
+ * Sync an embedding vector to an existing Neo4j node.
+ * Called after saveEpistemicNodeEmbedding completes, ensuring the
+ * embedding reaches Neo4j even if the initial node sync ran before
+ * the embedding was generated.
+ */
+declare const syncEmbeddingToNeo4j: any;
+declare const checkNeo4jHealth: any;
+/**
+ * Re-sync all epistemic nodes to Neo4j with updated properties (paginated)
+ * Use after adding new fields to the sync
+ */
+declare const resyncAllNodes: any;
+/**
+ * Re-sync all epistemic edges to Neo4j with updated properties (paginated)
+ * Use after adding new fields to the sync (e.g., classification fields)
+ */
+declare const resyncAllEdges: any;
+
+declare const neo4jSync_backfillAllToNeo4j: typeof backfillAllToNeo4j;
+declare const neo4jSync_checkNeo4jHealth: typeof checkNeo4jHealth;
+declare const neo4jSync_processRetryQueue: typeof processRetryQueue;
+declare const neo4jSync_resyncAllEdges: typeof resyncAllEdges;
+declare const neo4jSync_resyncAllNodes: typeof resyncAllNodes;
+declare const neo4jSync_syncAllEdgesToNeo4j: typeof syncAllEdgesToNeo4j;
+declare const neo4jSync_syncAllNodesToNeo4j: typeof syncAllNodesToNeo4j;
+declare const neo4jSync_syncEdgeToNeo4j: typeof syncEdgeToNeo4j;
+declare const neo4jSync_syncEmbeddingToNeo4j: typeof syncEmbeddingToNeo4j;
+declare const neo4jSync_syncNodeToNeo4j: typeof syncNodeToNeo4j;
+declare namespace neo4jSync {
+  export { neo4jSync_backfillAllToNeo4j as backfillAllToNeo4j, neo4jSync_checkNeo4jHealth as checkNeo4jHealth, neo4jSync_processRetryQueue as processRetryQueue, neo4jSync_resyncAllEdges as resyncAllEdges, neo4jSync_resyncAllNodes as resyncAllNodes, neo4jSync_syncAllEdgesToNeo4j as syncAllEdgesToNeo4j, neo4jSync_syncAllNodesToNeo4j as syncAllNodesToNeo4j, neo4jSync_syncEdgeToNeo4j as syncEdgeToNeo4j, neo4jSync_syncEmbeddingToNeo4j as syncEmbeddingToNeo4j, neo4jSync_syncNodeToNeo4j as syncNodeToNeo4j };
+}
+
+export { neo4jDriver, neo4jEdgeAPI, neo4jQueryRoute, neo4jSync };