@m6d/cortex-server 1.8.0 → 2.0.1

package/src/lib/graph/expand-domains.ts

@@ -1,276 +0,0 @@
-import type { ConceptDef, DomainDef, EndpointDef, RuleDef, ServiceDef } from "./types.ts";
-
-type DomainCollections = {
-    concepts: ConceptDef[];
-    endpoints: EndpointDef[];
-    services: ServiceDef[];
-    rules: RuleDef[];
-};
-
-type OwnershipMaps = {
-    concepts: WeakMap<ConceptDef, string>;
-    endpoints: WeakMap<EndpointDef, string>;
-    services: WeakMap<ServiceDef, string>;
-    rules: WeakMap<RuleDef, string>;
-};
-
-export function expandDomains(domains: Record<string, DomainDef>) {
-    const ownership = createOwnershipMaps(domains);
-    const expanded: Record<string, DomainDef> = {};
-
-    for (const [domainKey, domain] of Object.entries(domains)) {
-        const collections = cloneCollections(domain);
-        const pendingConcepts = [...collections.concepts];
-        const pendingEndpoints = [...collections.endpoints];
-        const pendingServices = [...collections.services];
-
-        while (
-            pendingConcepts.length > 0 ||
-            pendingEndpoints.length > 0 ||
-            pendingServices.length > 0
-        ) {
-            const concept = pendingConcepts.pop();
-            if (concept) {
-                includeConcept({
-                    domainKey,
-                    concept,
-                    ownership,
-                    collections,
-                    pendingConcepts,
-                    pendingEndpoints,
-                });
-            }
-
-            const endpoint = pendingEndpoints.pop();
-            if (endpoint) {
-                includeEndpoint({
-                    domainKey,
-                    endpoint,
-                    ownership,
-                    collections,
-                    pendingConcepts,
-                    pendingEndpoints,
-                });
-            }
-
-            const service = pendingServices.pop();
-            if (service) {
-                includeService({
-                    domainKey,
-                    service,
-                    ownership,
-                    collections,
-                    pendingConcepts,
-                });
-            }
-        }
-
-        expanded[domainKey] = {
-            ...domain,
-            concepts: collections.concepts,
-            endpoints: collections.endpoints,
-            services: collections.services,
-            rules: collections.rules,
-        };
-    }
-
-    return expanded;
-}
-
-function createOwnershipMaps(domains: Record<string, DomainDef>) {
-    const ownership: OwnershipMaps = {
-        concepts: new WeakMap<ConceptDef, string>(),
-        endpoints: new WeakMap<EndpointDef, string>(),
-        services: new WeakMap<ServiceDef, string>(),
-        rules: new WeakMap<RuleDef, string>(),
-    };
-
-    for (const [domainKey, domain] of Object.entries(domains)) {
-        for (const concept of domain.concepts ?? []) {
-            assignOwner(ownership.concepts, concept, domainKey);
-        }
-
-        for (const endpoint of domain.endpoints ?? []) {
-            assignOwner(ownership.endpoints, endpoint, domainKey);
-        }
-
-        for (const service of domain.services ?? []) {
-            assignOwner(ownership.services, service, domainKey);
-        }
-
-        for (const rule of domain.rules ?? []) {
-            assignOwner(ownership.rules, rule, domainKey);
-        }
-    }
-
-    return ownership;
-}
-
-function assignOwner<T extends object>(owners: WeakMap<T, string>, value: T, domainKey: string) {
-    if (!owners.has(value)) {
-        owners.set(value, domainKey);
-    }
-}
-
-function cloneCollections(domain: DomainDef) {
-    return {
-        concepts: [...(domain.concepts ?? [])],
-        endpoints: [...(domain.endpoints ?? [])],
-        services: [...(domain.services ?? [])],
-        rules: [...(domain.rules ?? [])],
-    } satisfies DomainCollections;
-}
-
-function includeConcept(options: {
-    domainKey: string;
-    concept: ConceptDef;
-    ownership: OwnershipMaps;
-    collections: DomainCollections;
-    pendingConcepts: ConceptDef[];
-    pendingEndpoints: EndpointDef[];
-}) {
-    const { domainKey, concept, ownership, collections, pendingConcepts, pendingEndpoints } =
-        options;
-
-    includeRule(domainKey, concept.governedBy ?? [], ownership, collections);
-
-    if (shouldAttach(ownership.concepts, concept, domainKey)) {
-        pushUnique(collections.concepts, concept);
-    }
-
-    if (
-        concept.parentConcept &&
-        shouldAttach(ownership.concepts, concept.parentConcept, domainKey)
-    ) {
-        if (pushUnique(collections.concepts, concept.parentConcept)) {
-            pendingConcepts.push(concept.parentConcept);
-        }
-    }
-
-    for (const endpoint of collections.endpoints) {
-        if (referencesConcept(endpoint, concept)) {
-            includeEndpoint({
-                domainKey,
-                endpoint,
-                ownership,
-                collections,
-                pendingConcepts,
-                pendingEndpoints,
-            });
-        }
-    }
-}
-
-function includeEndpoint(options: {
-    domainKey: string;
-    endpoint: EndpointDef;
-    ownership: OwnershipMaps;
-    collections: DomainCollections;
-    pendingConcepts: ConceptDef[];
-    pendingEndpoints: EndpointDef[];
-}) {
-    const { domainKey, endpoint, ownership, collections, pendingConcepts, pendingEndpoints } =
-        options;
-
-    if (shouldAttach(ownership.endpoints, endpoint, domainKey)) {
-        pushUnique(collections.endpoints, endpoint);
-    }
-
-    includeRule(domainKey, endpoint.governedBy ?? [], ownership, collections);
-
-    for (const concept of endpoint.queries ?? []) {
-        if (
-            shouldAttach(ownership.concepts, concept, domainKey) &&
-            pushUnique(collections.concepts, concept)
-        ) {
-            pendingConcepts.push(concept);
-        }
-    }
-
-    for (const concept of endpoint.mutates ?? []) {
-        if (
-            shouldAttach(ownership.concepts, concept, domainKey) &&
-            pushUnique(collections.concepts, concept)
-        ) {
-            pendingConcepts.push(concept);
-        }
-    }
-
-    for (const returned of endpoint.returns ?? []) {
-        if (
-            shouldAttach(ownership.concepts, returned.concept, domainKey) &&
-            pushUnique(collections.concepts, returned.concept)
-        ) {
-            pendingConcepts.push(returned.concept);
-        }
-    }
-
-    for (const dependency of endpoint.dependsOn ?? []) {
-        if (
-            shouldAttach(ownership.endpoints, dependency.endpoint, domainKey) &&
-            pushUnique(collections.endpoints, dependency.endpoint)
-        ) {
-            pendingEndpoints.push(dependency.endpoint);
-        }
-    }
-}
-
-function includeService(options: {
-    domainKey: string;
-    service: ServiceDef;
-    ownership: OwnershipMaps;
-    collections: DomainCollections;
-    pendingConcepts: ConceptDef[];
-}) {
-    const { domainKey, service, ownership, collections, pendingConcepts } = options;
-
-    if (shouldAttach(ownership.services, service, domainKey)) {
-        pushUnique(collections.services, service);
-    }
-
-    includeRule(domainKey, service.governedBy ?? [], ownership, collections);
-
-    if (
-        shouldAttach(ownership.concepts, service.belongsTo, domainKey) &&
-        pushUnique(collections.concepts, service.belongsTo)
-    ) {
-        pendingConcepts.push(service.belongsTo);
-    }
-}
-
-function includeRule(
-    domainKey: string,
-    rules: readonly RuleDef[],
-    ownership: OwnershipMaps,
-    collections: DomainCollections,
-) {
-    for (const rule of rules) {
-        if (shouldAttach(ownership.rules, rule, domainKey)) {
-            pushUnique(collections.rules, rule);
-        }
-    }
-}
-
-function shouldAttach<T extends object>(owners: WeakMap<T, string>, value: T, domainKey: string) {
-    const owner = owners.get(value);
-    return owner == null || owner === domainKey;
-}
-
-function pushUnique<T extends object>(values: T[], value: T) {
-    if (values.includes(value)) {
-        return false;
-    }
-
-    values.push(value);
-    return true;
-}
-
-function referencesConcept(endpoint: EndpointDef, concept: ConceptDef) {
-    return (
-        endpoint.queries?.includes(concept) ||
-        endpoint.mutates?.includes(concept) ||
-        endpoint.returns?.some(function (returned) {
-            return returned.concept === concept;
-        })
-    );
-}

package/src/lib/graph/generate-cypher.ts

@@ -1,192 +0,0 @@
-/**
- * Transforms declarative DomainDef into idempotent MERGE-based Cypher.
- *
- * Returns two phases:
- *   - `nodes`  -- MERGE statements that create/update Domain, Concept, Endpoint,
- *                 Service, and Rule nodes.
- *   - `edges`  -- MATCH+MERGE statements that wire up relationships between nodes.
- *
- * The caller MUST run all `nodes` from every module before running any `edges`,
- * because edges may reference nodes defined in a different module (e.g. a Rule
- * in the leaves module that GOVERNS a Concept created by the servicing module).
- */
-
-import type { DomainDef } from "./types.ts";
-
-export type GeneratedCypher = {
-    nodes: string[];
-    edges: string[];
-};
-
-function esc(s: string) {
-    return s.replace(/\\/g, "\\\\").replace(/'/g, "\\'").replace(/\n/g, "\\n");
-}
-
-function jsonStr(value: unknown) {
-    return esc(JSON.stringify(value));
-}
-
-export function generateCypher(data: DomainDef) {
-    const nodes: string[] = [];
-    const edges: string[] = [];
-
-    // -- Domain node --
-    const domainMeta = data.metadata
-        ? `,\n            d.metadata = '${jsonStr(data.metadata)}'`
-        : "";
-    nodes.push(
-        `MERGE (d:Domain {name: '${esc(data.name)}'})
-        SET d.description = '${esc(data.description)}'${domainMeta}`,
-    );
-
-    // -- Concept nodes --
-    for (const c of data.concepts ?? []) {
-        const aliasClause =
-            c.aliases && c.aliases.length > 0
-                ? `, c.aliases = [${c.aliases.map((a) => `'${esc(a)}'`).join(", ")}]`
-                : "";
-        const conceptMeta = c.metadata ? `, c.metadata = '${jsonStr(c.metadata)}'` : "";
-
-        nodes.push(
-            `MERGE (c:Concept {name: '${esc(c.name)}'})
-            SET c.description = '${esc(c.description)}'${aliasClause}${conceptMeta}`,
-        );
-
-        edges.push(
-            `MATCH (c:Concept {name: '${esc(c.name)}'})
-            MATCH (d:Domain {name: '${esc(data.name)}'})
-            MERGE (c)-[:BELONGS_TO]->(d)`,
-        );
-
-        if (c.parentConcept) {
-            edges.push(
-                `MATCH (child:Concept {name: '${esc(c.name)}'})
-                MATCH (parent:Concept {name: '${esc(c.parentConcept.name)}'})
-                MERGE (child)-[:SPECIALIZES]->(parent)`,
-            );
-        }
-
-        c.governedBy?.forEach((rule) => {
-            edges.push(
-                `MATCH (r:Rule {name: '${esc(rule.name)}'})
-                MATCH (t:Concept {name: '${esc(c.name)}'})
-                MERGE (r)-[:GOVERNS]->(t)`,
-            );
-        });
-    }
-
-    // -- Endpoint nodes --
-    for (const ep of data.endpoints ?? []) {
-        const endpointMeta = ep.metadata
-            ? `,\n                e.metadata = '${jsonStr(ep.metadata)}'`
-            : "";
-        nodes.push(
-            `MERGE (e:Endpoint {path: '${esc(ep.path)}', method: '${ep.method}'})
-            SET e.name = '${esc(ep.name)}',
-                e.description = '${esc(ep.description)}',
-                e.params = '${jsonStr(ep.params)}',
-                e.body = '${jsonStr(ep.body)}',
-                e.response = '${jsonStr(ep.response)}',
-                e.propertiesDescriptions = '${jsonStr(ep.propertiesDescriptions)}',
-                e.successStatus = ${ep.successStatus},
-                e.errorStatuses = [${ep.errorStatuses.join(", ")}]${endpointMeta}`,
-        );
-
-        for (const concept of ep.queries ?? []) {
-            edges.push(
-                `MATCH (c:Concept {name: '${esc(concept.name)}'})
-                MATCH (e:Endpoint {path: '${esc(ep.path)}', method: '${ep.method}'})
-                MERGE (c)-[:QUERIED_VIA]->(e)`,
-            );
-        }
-
-        for (const concept of ep.mutates ?? []) {
-            edges.push(
-                `MATCH (c:Concept {name: '${esc(concept.name)}'})
-                MATCH (e:Endpoint {path: '${esc(ep.path)}', method: '${ep.method}'})
-                MERGE (c)-[:MUTATED_VIA]->(e)`,
-            );
-        }
-
-        for (const ret of ep.returns ?? []) {
-            const fieldClause = ret.field ? ` SET r.field = '${esc(ret.field)}'` : "";
-
-            edges.push(
-                `MATCH (e:Endpoint {path: '${esc(ep.path)}', method: '${ep.method}'})
-                MATCH (c:Concept {name: '${esc(ret.concept.name)}'})
-                MERGE (e)-[r:RETURNS]->(c)${fieldClause}`,
-            );
-        }
-
-        for (const rule of ep.governedBy ?? []) {
-            edges.push(
-                `MATCH (r:Rule {name: '${esc(rule.name)}'})
-                MATCH (t:Endpoint {path: '${esc(ep.path)}', method: '${ep.method}'})
-                MERGE (r)-[:GOVERNS]->(t)`,
-            );
-        }
-
-        for (const dep of ep.dependsOn ?? []) {
-            edges.push(
-                `MATCH (e:Endpoint {path: '${esc(ep.path)}', method: '${ep.method}'})
-                MATCH (dep:Endpoint {path: '${esc(dep.endpoint.path)}', method: '${dep.endpoint.method}'})
-                MERGE (e)-[d:DEPENDS_ON]->(dep)
-                SET d.paramName = '${esc(dep.paramName)}', d.fromField = '${esc(dep.fromField)}'`,
-            );
-        }
-    }
-
-    // -- Service nodes --
-    for (const svc of data.services ?? []) {
-        const serviceMeta = svc.metadata
-            ? `,\n            s.metadata = '${jsonStr(svc.metadata)}'`
-            : "";
-        nodes.push(
-            `MERGE (s:Service {builtInId: '${esc(svc.builtInId)}'})
-            SET s.name = '${esc(svc.name)}',
-            s.description = '${esc(svc.description)}'${serviceMeta}`,
-        );
-
-        edges.push(
-            `MATCH (c:Concept {name: '${esc(svc.belongsTo.name)}'})
-            MATCH (s:Service {builtInId: '${esc(svc.builtInId)}'})
-            MERGE (c)-[:REQUESTED_VIA]->(s)`,
-        );
-
-        svc.governedBy?.forEach((rule) => {
-            edges.push(
-                `MATCH (r:Rule {name: '${esc(rule.name)}'})
-                MATCH (t:Service {builtInId: '${esc(svc.builtInId)}'})
-                MERGE (r)-[:GOVERNS]->(t)`,
-            );
-        });
-    }
-
-    // -- Rule nodes --
-    for (const rule of data.rules ?? []) {
-        const ruleMeta = rule.metadata
-            ? `,\n            r.metadata = '${jsonStr(rule.metadata)}'`
-            : "";
-        nodes.push(
-            `MERGE (r:Rule {name: '${esc(rule.name)}'})
-            SET r.description = '${esc(rule.description)}'${ruleMeta}`,
-        );
-    }
-
-    return { nodes, edges } satisfies GeneratedCypher;
-}
-
-export function toCypherScript(data: DomainDef) {
-    const { nodes, edges } = generateCypher(data);
-    return (
-        `// Auto-generated seed script for module: ${data.name}\n` +
-        `// Generated at: ${new Date().toISOString()}\n` +
-        `// Safe to re-run (uses MERGE)\n\n` +
-        `// --- Nodes ---\n` +
-        nodes.join(";\n\n") +
-        ";\n\n" +
-        `// --- Edges ---\n` +
-        edges.join(";\n\n") +
-        ";\n"
-    );
-}

package/src/lib/graph/seed.ts

@@ -1,162 +0,0 @@
-/**
- * Seed orchestrator for the knowledge graph.
- *
- * Validates domains, generates Cypher, executes against Neo4j,
- * and generates concept embeddings. All configuration is passed
- * explicitly — no environment variables or Convex dependencies.
- */
-
-import type { EmbeddingModel } from "ai";
-import { embed } from "ai";
-import type { Neo4jClient, Neo4jConfig } from "./neo4j.ts";
-import { createNeo4jClient } from "./neo4j.ts";
-import { expandDomains } from "./expand-domains.ts";
-import { generateCypher, type GeneratedCypher } from "./generate-cypher.ts";
-import type { DomainDef } from "./types.ts";
-import { validateDomain } from "./validate.ts";
-
-// ---------------------------------------------------------------------------
-// Config
-// ---------------------------------------------------------------------------
-
-export type EmbeddingConfig = {
-    model: EmbeddingModel;
-    dimension: number;
-};
-
-export type SeedGraphConfig = {
-    neo4j: Neo4jConfig;
-    embedding: EmbeddingConfig;
-};
-
-// ---------------------------------------------------------------------------
-// Internal helpers
-// ---------------------------------------------------------------------------
-
-async function runStatements(client: Neo4jClient, label: string, statements: string[]) {
-    console.log(`\n--- ${label} (${statements.length} statements) ---`);
-
-    let success = 0;
-    let failed = 0;
-
-    for (const stmt of statements) {
-        try {
-            const result = await client.query(stmt);
-            const parsed = JSON.parse(result);
-            if (parsed.error) {
-                console.error(`  ✗ Failed: ${parsed.message}`);
-                console.error(`    Statement: ${stmt.substring(0, 120)}...`);
-                failed++;
-            } else {
-                success++;
-            }
-        } catch (e) {
-            console.error(`  ✗ Exception: ${e}`);
-            console.error(`    Statement: ${stmt.substring(0, 120)}...`);
-            failed++;
-        }
-    }
-
-    console.log(`  ✓ ${success} succeeded, ${failed} failed`);
-}
-
-async function generateEmbeddings(client: Neo4jClient, embeddingConfig: EmbeddingConfig) {
-    console.log("Seeding concept embeddings...");
-
-    // 1. Create the vector index (idempotent)
-    await client.query(
-        `CREATE VECTOR INDEX concept_embeddings IF NOT EXISTS
-             FOR (c:Concept) ON (c.embedding)
-             OPTIONS {indexConfig: {
-                 \`vector.dimensions\`: ${embeddingConfig.dimension},
-                 \`vector.similarity_function\`: 'cosine'
-             }}`,
-    );
-    console.log("Vector index created (or already exists)");
-
-    // 2. Fetch all concepts
-    const conceptsRaw = await client.query(
-        "MATCH (c:Concept) RETURN c.name AS name, c.description AS description",
-    );
-    const concepts: { name: string; description: string }[] = JSON.parse(conceptsRaw);
-
-    if (!Array.isArray(concepts) || concepts.length === 0) {
-        console.log("No concepts found in Neo4j");
-        return;
-    }
-
-    console.log(`Found ${concepts.length} concepts, generating embeddings...`);
-
-    // 3. Generate and store embeddings for each concept
-    const embeddingResults = await Promise.all(
-        concepts.map(async (concept) => ({
-            concept,
-            embedding: (
-                await embed({
-                    model: embeddingConfig.model,
-                    value: concept.description,
-                })
-            ).embedding,
-        })),
-    );
-
-    // 4. Store the embeddings in the graph
-    await Promise.all(
-        embeddingResults.map(
-            async (result) =>
-                await client.query(
-                    `MATCH (c:Concept {name: $name})
-                     SET c.embedding = $embedding`,
-                    {
-                        name: result.concept.name,
-                        embedding: result.embedding,
-                    },
-                ),
-        ),
-    );
-
-    console.log("Embedding seeding complete!");
-}
-
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-
-export async function seedGraph(config: SeedGraphConfig, domains: Record<string, DomainDef>) {
-    const expandedDomains = expandDomains(domains);
-
-    // Validate all domains
-    const validationErrors = Object.entries(expandedDomains).flatMap(([name, domain]) =>
-        validateDomain(domain).map((err) => `[${name}] ${err}`),
-    );
-
-    if (validationErrors.length) {
-        validationErrors.forEach((err) => console.error(err));
-        throw new Error(`Validation failed with ${validationErrors.length} error(s)`);
-    }
-
-    const client = createNeo4jClient(config.neo4j, config.embedding.model);
-    const targets = Object.entries(expandedDomains);
-
-    console.log(`Seeding ${targets.length} domain(s)...`);
-
-    // Generate Cypher for all target domains
-    const allCypher: [string, GeneratedCypher][] = targets.map(([name, data]) => [
-        name,
-        generateCypher(data),
-    ]);
-
-    // Phase 1: Create all nodes across every domain first.
-    // This ensures cross-domain references resolve correctly.
-    const allNodes = allCypher.flatMap(([, c]) => c.nodes);
-    await runStatements(client, "Phase 1: Nodes", allNodes);
-
-    // Phase 2: Create all edges now that every node exists.
-    const allEdges = allCypher.flatMap(([, c]) => c.edges);
-    await runStatements(client, "Phase 2: Edges", allEdges);
-
-    console.log("\nGraph seeding complete!");
-
-    // Phase 3: Generate embeddings for concepts
-    await generateEmbeddings(client, config.embedding);
-}

package/src/lib/graph/validate.ts

@@ -1,78 +0,0 @@
-import type { DomainDef } from "./types.ts";
-
-export function validateDomain(data: DomainDef) {
-    const errors: string[] = [];
-
-    const seenConceptNames = new Set<string>();
-    for (const c of data.concepts ?? []) {
-        if (seenConceptNames.has(c.name)) {
-            errors.push(`Duplicate concept name: "${c.name}"`);
-        }
-        seenConceptNames.add(c.name);
-    }
-
-    const seenEndpointNames = new Set<string>();
-    for (const e of data.endpoints ?? []) {
-        if (seenEndpointNames.has(e.name)) {
-            errors.push(`Duplicate endpoint name: "${e.name}"`);
-        }
-        seenEndpointNames.add(e.name);
-    }
-
-    const seenServiceNames = new Set<string>();
-    for (const s of data.services ?? []) {
-        if (seenServiceNames.has(s.name)) {
-            errors.push(`Duplicate service name: "${s.name}"`);
-        }
-        seenServiceNames.add(s.name);
-    }
-
-    const seenRuleNames = new Set<string>();
-    for (const r of data.rules ?? []) {
-        if (seenRuleNames.has(r.name)) {
-            errors.push(`Duplicate rule name: "${r.name}"`);
-        }
-        seenRuleNames.add(r.name);
-    }
-
-    // Cross-domain references are allowed (concepts/endpoints/services may
-    // be defined in another domain), so we do not enforce local membership.
-
-    const referencedConcepts = new Set<string>();
-    const referencedRules = new Set<string>();
-
-    for (const ep of data.endpoints ?? []) {
-        ep.queries?.forEach((c) => referencedConcepts.add(c.name));
-        ep.mutates?.forEach((c) => referencedConcepts.add(c.name));
-        ep.returns?.forEach((r) => referencedConcepts.add(r.concept.name));
-        ep.governedBy?.forEach((r) => referencedRules.add(r.name));
-    }
-
-    for (const svc of data.services ?? []) {
-        referencedConcepts.add(svc.belongsTo.name);
-        svc.governedBy?.forEach((r) => referencedRules.add(r.name));
-    }
-
-    for (const c of data.concepts ?? []) {
-        c.governedBy?.forEach((r) => referencedRules.add(r.name));
-        if (c.parentConcept) {
-            referencedConcepts.add(c.parentConcept.name);
-        }
-    }
-
-    for (const c of data.concepts ?? []) {
-        if (!referencedConcepts.has(c.name)) {
-            errors.push(`Concept "${c.name}" is never referenced by any endpoint, or service`);
-        }
-    }
-
-    for (const r of data.rules ?? []) {
-        if (!referencedRules.has(r.name)) {
-            errors.push(
-                `Rule "${r.name}" is never referenced by any endpoint, service, or concept`,
-            );
-        }
-    }
-
-    return errors;
-}