@m6d/cortex-server 1.4.0 → 1.5.0

package/dist/src/graph/expand-domains.d.ts

@@ -0,0 +1,2 @@
+import type { DomainDef } from "./types.ts";
+export declare function expandDomains(domains: Record<string, DomainDef>): Record<string, DomainDef>;

package/dist/src/graph/helpers.d.ts

@@ -8,17 +8,20 @@ export declare function defineConcept(def: Omit<ConceptDef, "__brand">): {
     aliases?: string[] | undefined;
     parentConcept?: ConceptDef | undefined;
     governedBy?: RuleDef[] | undefined;
+    metadata?: Record<string, unknown> | undefined;
     __brand: "concept";
 };
 export declare function defineRule(def: Omit<RuleDef, "__brand">): {
     name: string;
     description: string;
+    metadata?: Record<string, unknown> | undefined;
     __brand: "rule";
 };
 export declare function defineService(def: Omit<ServiceDef, "__brand">): {
     name: string;
     description: string;
     governedBy?: RuleDef[] | undefined;
+    metadata?: Record<string, unknown> | undefined;
     builtInId: string;
     belongsTo: ConceptDef;
     __brand: "service";
@@ -26,6 +29,7 @@ export declare function defineService(def: Omit<ServiceDef, "__brand">): {
 export declare function defineDomain(def: Omit<DomainDef, "__brand">): {
     name: string;
     description: string;
+    metadata?: Record<string, unknown> | undefined;
     concepts?: ConceptDef[] | undefined;
     endpoints?: EndpointDef[] | undefined;
     services?: ServiceDef[] | undefined;
@@ -57,4 +61,5 @@ export declare function defineEndpoint(input: EndpointInput): {
         fromField: string;
     }[] | undefined;
     governedBy: RuleDef[] | undefined;
+    metadata: Record<string, unknown> | undefined;
 };

package/dist/src/graph/resolver.d.ts

@@ -34,6 +34,7 @@ export type ResolvedEndpoint = {
     response: string;
     dependencies: EndpointDependency[];
     rules: string[];
+    metadata: string;
 };
 export type ResolvedService = {
     concept: string;
@@ -41,6 +42,7 @@ export type ResolvedService = {
     builtInId: string;
     description: string;
     rules: string[];
+    metadata: string;
 };
 export type ResolvedContext = {
     readEndpoints: ResolvedEndpoint[];

package/dist/src/graph/types.d.ts

@@ -31,6 +31,7 @@ export type ConceptDef = {
     aliases?: string[];
     parentConcept?: ConceptDef;
     governedBy?: RuleDef[];
+    metadata?: Record<string, unknown>;
 };
 export type EndpointDef = {
     readonly __brand: "endpoint";
@@ -57,6 +58,7 @@ export type EndpointDef = {
         fromField: string;
     }[];
     governedBy?: RuleDef[];
+    metadata?: Record<string, unknown>;
 };
 export type EndpointInput = {
     name: string;
@@ -79,6 +81,7 @@ export type EndpointInput = {
         fromField: string;
     }[];
     governedBy?: RuleDef[];
+    metadata?: Record<string, unknown>;
 };
 export type ServiceDef = {
     readonly __brand: "service";
@@ -87,11 +90,13 @@ export type ServiceDef = {
     builtInId: string;
     belongsTo: ConceptDef;
     governedBy?: RuleDef[];
+    metadata?: Record<string, unknown>;
 };
 export type RuleDef = {
     readonly __brand: "rule";
     name: string;
     description: string;
+    metadata?: Record<string, unknown>;
 };
 export type DomainDef = {
     readonly __brand: "domain";
@@ -101,4 +106,5 @@ export type DomainDef = {
     endpoints?: EndpointDef[];
     services?: ServiceDef[];
     rules?: RuleDef[];
+    metadata?: Record<string, unknown>;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@m6d/cortex-server",
-    "version": "1.4.0",
+    "version": "1.5.0",
     "description": "Reusable AI agent chat server library for Hono + Bun",
     "license": "MIT",
     "type": "module",

package/src/ai/prompt.ts

@@ -65,6 +65,7 @@ The following endpoints were automatically matched to the user's message.`,
                       )
                       .join("\n")
                 : "";
+        const meta = ep.metadata !== "{}" ? `\n- Metadata: ${ep.metadata}` : "";
         parts.push(
             `
 ### ${ep.concept} (read)
@@ -72,7 +73,7 @@ The following endpoints were automatically matched to the user's message.`,
 - ${ep.method} ${ep.path}
 - Params: ${ep.params}
 - Body: ${ep.body}
-- Response: ${ep.response}${rules}${deps}`,
+- Response: ${ep.response}${rules}${deps}${meta}`,
         );
     }
 
@@ -88,6 +89,7 @@ The following endpoints were automatically matched to the user's message.`,
                       )
                       .join("\n")
                 : "";
+        const meta = ep.metadata !== "{}" ? `\n- Metadata: ${ep.metadata}` : "";
         parts.push(
             `
 ### ${ep.concept} (write)
@@ -95,17 +97,18 @@ The following endpoints were automatically matched to the user's message.`,
 - ${ep.method} ${ep.path}
 - Params: ${ep.params}
 - Body: ${ep.body}
-- Response: ${ep.response}${rules}${deps}`,
+- Response: ${ep.response}${rules}${deps}${meta}`,
         );
     }
 
     for (const svc of resolved.services) {
         const rules = svc.rules.length > 0 ? `\n  Rules: ${svc.rules.join("; ")}` : "";
+        const meta = svc.metadata !== "{}" ? `\n- Metadata: ${svc.metadata}` : "";
         parts.push(
             `
 ### ${svc.concept} via ${svc.serviceName} (service)
 - Built-in ID: ${svc.builtInId}
-- Description: ${svc.description || "N/A"}${rules}`,
+- Description: ${svc.description || "N/A"}${rules}${meta}`,
         );
     }
 

package/src/graph/expand-domains.ts

@@ -0,0 +1,276 @@
+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/graph/generate-cypher.ts

@@ -31,9 +31,12 @@ export function generateCypher(data: DomainDef) {
     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)}'`,
+        SET d.description = '${esc(data.description)}'${domainMeta}`,
     );
 
     // -- Concept nodes --
@@ -42,10 +45,11 @@ export function generateCypher(data: DomainDef) {
             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}`,
+            SET c.description = '${esc(c.description)}'${aliasClause}${conceptMeta}`,
         );
 
         edges.push(
@@ -73,6 +77,9 @@ export function generateCypher(data: DomainDef) {
 
     // -- 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)}',
@@ -82,7 +89,7 @@ export function generateCypher(data: DomainDef) {
                 e.response = '${jsonStr(ep.response)}',
                 e.propertiesDescriptions = '${jsonStr(ep.propertiesDescriptions)}',
                 e.successStatus = ${ep.successStatus},
-                e.errorStatuses = [${ep.errorStatuses.join(", ")}]`,
+                e.errorStatuses = [${ep.errorStatuses.join(", ")}]${endpointMeta}`,
         );
 
         for (const concept of ep.queries ?? []) {
@@ -131,10 +138,13 @@ export function generateCypher(data: DomainDef) {
 
     // -- 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)}'`,
+            s.description = '${esc(svc.description)}'${serviceMeta}`,
         );
 
         edges.push(
@@ -154,9 +164,12 @@ export function generateCypher(data: DomainDef) {
 
     // -- 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)}'`,
+            SET r.description = '${esc(rule.description)}'${ruleMeta}`,
         );
     }
 

package/src/graph/helpers.ts

@@ -64,5 +64,6 @@ export function defineEndpoint(input: EndpointInput) {
         returns: input.returns,
         dependsOn: input.dependsOn,
         governedBy: input.governedBy,
+        metadata: input.metadata,
     } satisfies EndpointDef;
 }

package/src/graph/resolver.ts

@@ -50,6 +50,7 @@ export type ResolvedEndpoint = {
     response: string;
     dependencies: EndpointDependency[];
     rules: string[];
+    metadata: string;
 };
 
 export type ResolvedService = {
@@ -58,6 +59,7 @@ export type ResolvedService = {
     builtInId: string;
     description: string;
     rules: string[];
+    metadata: string;
 };
 
 export type ResolvedContext = {
@@ -79,6 +81,7 @@ type EndpointRow = {
     params: string | null;
     body: string | null;
     response: string | null;
+    metadata: string | null;
     dependencies: (EndpointDependency | { depPath: null })[];
     rules: (string | null)[];
 };
@@ -88,6 +91,7 @@ type ServiceRow = {
     serviceName: string;
     builtInId: string;
     description: string | null;
+    metadata: string | null;
     rules: (string | null)[];
 };
 
@@ -158,6 +162,7 @@ export async function resolveFromGraph(prompt: string, config: ResolverConfig) {
                     e.params AS params,
                     e.body AS body,
                     e.response AS response,
+                    e.metadata AS metadata,
                     dependencies,
                     collect(DISTINCT rEndpoint.description) +
                     collect(DISTINCT rConcept.description) AS rules`,
@@ -177,6 +182,7 @@ export async function resolveFromGraph(prompt: string, config: ResolverConfig) {
                     params: row.params ?? "[]",
                     body: row.body ?? "[]",
                     response: row.response ?? "[]",
+                    metadata: row.metadata ?? "{}",
                     dependencies: row.dependencies.filter(
                         (dep): dep is EndpointDependency => dep.depPath != null,
                     ),
@@ -198,6 +204,7 @@ export async function resolveFromGraph(prompt: string, config: ResolverConfig) {
                     svc.name AS serviceName,
                     svc.builtInId AS builtInId,
                     svc.description AS description,
+                    svc.metadata AS metadata,
                     collect(DISTINCT rService.description) +
                     collect(DISTINCT rConcept.description) AS rules`,
             { names: conceptNames },
@@ -210,6 +217,7 @@ export async function resolveFromGraph(prompt: string, config: ResolverConfig) {
                     serviceName: row.serviceName,
                     builtInId: row.builtInId,
                     description: row.description ?? "",
+                    metadata: row.metadata ?? "{}",
                     rules: row.rules.filter((rule): rule is string => Boolean(rule)),
                 };
             }),
@@ -239,6 +247,7 @@ export async function resolveFromGraph(prompt: string, config: ResolverConfig) {
                         e.params AS params,
                         e.body AS body,
                         e.response AS response,
+                        e.metadata AS metadata,
                         dependencies,
                         collect(DISTINCT rEndpoint.description) +
                         collect(DISTINCT rConcept.description) AS rules`,
@@ -259,6 +268,7 @@ export async function resolveFromGraph(prompt: string, config: ResolverConfig) {
                         params: row.params ?? "[]",
                         body: row.body ?? "[]",
                         response: row.response ?? "[]",
+                        metadata: row.metadata ?? "{}",
                         dependencies: row.dependencies.filter(
                             (dep): dep is EndpointDependency => dep.depPath != null,
                         ),

package/src/graph/seed.ts

@@ -10,6 +10,7 @@ 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";
@@ -122,8 +123,10 @@ async function generateEmbeddings(client: Neo4jClient, embeddingConfig: Embeddin
 // ---------------------------------------------------------------------------
 
 export async function seedGraph(config: SeedGraphConfig, domains: Record<string, DomainDef>) {
+    const expandedDomains = expandDomains(domains);
+
     // Validate all domains
-    const validationErrors = Object.entries(domains).flatMap(([name, domain]) =>
+    const validationErrors = Object.entries(expandedDomains).flatMap(([name, domain]) =>
         validateDomain(domain).map((err) => `[${name}] ${err}`),
     );
 
@@ -133,7 +136,7 @@ export async function seedGraph(config: SeedGraphConfig, domains: Record<string,
     }
 
     const client = createNeo4jClient(config.neo4j, config.embedding.model);
-    const targets = Object.entries(domains);
+    const targets = Object.entries(expandedDomains);
 
     console.log(`Seeding ${targets.length} domain(s)...`);
 

package/src/graph/types.ts

@@ -52,6 +52,7 @@ export type ConceptDef = {
     aliases?: string[];
     parentConcept?: ConceptDef;
     governedBy?: RuleDef[];
+    metadata?: Record<string, unknown>;
 };
 
 // ---------------------------------------------------------------------------
@@ -84,6 +85,7 @@ export type EndpointDef = {
     }[];
 
     governedBy?: RuleDef[];
+    metadata?: Record<string, unknown>;
 };
 
 // ---------------------------------------------------------------------------
@@ -112,6 +114,7 @@ export type EndpointInput = {
     }[];
 
     governedBy?: RuleDef[];
+    metadata?: Record<string, unknown>;
 };
 
 // ---------------------------------------------------------------------------
@@ -125,6 +128,7 @@ export type ServiceDef = {
     builtInId: string;
     belongsTo: ConceptDef;
     governedBy?: RuleDef[];
+    metadata?: Record<string, unknown>;
 };
 
 // ---------------------------------------------------------------------------
@@ -135,6 +139,7 @@ export type RuleDef = {
     readonly __brand: "rule";
     name: string;
     description: string;
+    metadata?: Record<string, unknown>;
 };
 
 // ---------------------------------------------------------------------------
@@ -149,4 +154,5 @@ export type DomainDef = {
     endpoints?: EndpointDef[];
     services?: ServiceDef[];
     rules?: RuleDef[];
+    metadata?: Record<string, unknown>;
 };

package/dist/src/ai/active-streams.test.d.ts

@@ -1 +0,0 @@
-export {};

package/src/ai/active-streams.test.ts

@@ -1,21 +0,0 @@
-import { afterEach, describe, expect, it } from "bun:test";
-import { registerStream, removeStream, subscribe } from "./active-streams.ts";
-
-describe("active-streams", function () {
-    afterEach(function () {
-        removeStream("thread-under-test");
-    });
-
-    it("does not remove a newer stream when cleaning up an older one", function () {
-        const firstStream = registerStream("thread-under-test", new AbortController());
-        const secondStream = registerStream("thread-under-test", new AbortController());
-
-        removeStream("thread-under-test", firstStream.id);
-
-        expect(subscribe("thread-under-test")).not.toBeNull();
-
-        removeStream("thread-under-test", secondStream.id);
-
-        expect(subscribe("thread-under-test")).toBeNull();
-    });
-});