@hazeljs/kag 0.0.0-stage → 2.0.9

package/dist/planner/industry-profiles.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Industry / domain query templates for HeuristicQueryPlanner.
+ *
+ * Core KAG stays industry-agnostic. Apps compose a profile (or merge several)
+ * that matches their relation vocabulary — commerce, healthcare, ops, etc.
+ */
+export interface QueryTemplate {
+    name: string;
+    /** Matched against the natural-language question. */
+    pattern: RegExp;
+    /** Optional relation-type filter for BFS. Omit to traverse all edges. */
+    relationTypes?: string[];
+    depth?: number;
+}
+export interface IndustryProfile {
+    /** Stable id, e.g. "commerce", "healthcare", "generic". */
+    id: string;
+    templates: QueryTemplate[];
+    /** Default traversal depth when no template matches. */
+    defaultDepth?: number;
+}
+/**
+ * Domain-neutral defaults: intent shaping only — no industry relation names.
+ * Relation filters are left open so any graph vocabulary works.
+ */
+export declare const GENERIC_INDUSTRY_PROFILE: IndustryProfile;
+/**
+ * Optional commerce / payments vocabulary (orders, refunds, settlements).
+ * Pass explicitly — never the default for all KAG apps.
+ */
+export declare const COMMERCE_INDUSTRY_PROFILE: IndustryProfile;
+/** Merge profiles; later templates win on same `name`. */
+export declare function mergeIndustryProfiles(...profiles: IndustryProfile[]): IndustryProfile;
+//# sourceMappingURL=industry-profiles.d.ts.map

package/dist/planner/industry-profiles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"industry-profiles.d.ts","sourceRoot":"","sources":["../../src/planner/industry-profiles.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,yEAAyE;IACzE,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,2DAA2D;IAC3D,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,aAAa,EAAE,CAAC;IAC3B,wDAAwD;IACxD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;GAGG;AACH,eAAO,MAAM,wBAAwB,EAAE,eAoBtC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,yBAAyB,EAAE,eAuBvC,CAAC;AAEF,0DAA0D;AAC1D,wBAAgB,qBAAqB,CAAC,GAAG,QAAQ,EAAE,eAAe,EAAE,GAAG,eAAe,CAkBrF"}

package/dist/planner/industry-profiles.js

@@ -0,0 +1,83 @@
+"use strict";
+/**
+ * Industry / domain query templates for HeuristicQueryPlanner.
+ *
+ * Core KAG stays industry-agnostic. Apps compose a profile (or merge several)
+ * that matches their relation vocabulary — commerce, healthcare, ops, etc.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COMMERCE_INDUSTRY_PROFILE = exports.GENERIC_INDUSTRY_PROFILE = void 0;
+exports.mergeIndustryProfiles = mergeIndustryProfiles;
+/**
+ * Domain-neutral defaults: intent shaping only — no industry relation names.
+ * Relation filters are left open so any graph vocabulary works.
+ */
+exports.GENERIC_INDUSTRY_PROFILE = {
+    id: 'generic',
+    defaultDepth: 3,
+    templates: [
+        {
+            name: 'causal',
+            pattern: /\b(why|cause|because|reason|led to|resulted|affect|impact|driven)\b/i,
+            depth: 4,
+        },
+        {
+            name: 'temporal',
+            pattern: /\b(when|was|were|before|after|changed|previously|currently|as of)\b/i,
+            depth: 3,
+        },
+        {
+            name: 'comparison',
+            pattern: /\b(lower|higher|vs|versus|compared|difference|delta|increase|decrease)\b/i,
+            depth: 3,
+        },
+    ],
+};
+/**
+ * Optional commerce / payments vocabulary (orders, refunds, settlements).
+ * Pass explicitly — never the default for all KAG apps.
+ */
+exports.COMMERCE_INDUSTRY_PROFILE = {
+    id: 'commerce',
+    defaultDepth: 3,
+    templates: [
+        {
+            name: 'settlement',
+            pattern: /settlement|payout|profit|revenue|merchant/i,
+            relationTypes: ['HAS_ORDER', 'HAS_PAYMENT', 'HAS_REFUND', 'HAS_FEE', 'AFFECTS', 'SETTLED_BY'],
+            depth: 4,
+        },
+        {
+            name: 'refund',
+            pattern: /refund/i,
+            relationTypes: ['HAS_ORDER', 'HAS_PAYMENT', 'HAS_REFUND', 'REFUNDED_BY'],
+            depth: 3,
+        },
+        {
+            name: 'price',
+            pattern: /price|catalog|sku|product cost/i,
+            relationTypes: ['HAS_PRODUCT', 'PRICED_AS'],
+            depth: 2,
+        },
+    ],
+};
+/** Merge profiles; later templates win on same `name`. */
+function mergeIndustryProfiles(...profiles) {
+    const byName = new Map();
+    let defaultDepth = 3;
+    const ids = [];
+    for (const profile of profiles) {
+        ids.push(profile.id);
+        if (profile.defaultDepth !== undefined) {
+            defaultDepth = profile.defaultDepth;
+        }
+        for (const template of profile.templates) {
+            byName.set(template.name, template);
+        }
+    }
+    return {
+        id: ids.join('+') || 'custom',
+        defaultDepth,
+        templates: [...byName.values()],
+    };
+}

package/dist/resolution/entity-resolver.d.ts

@@ -0,0 +1,21 @@
+import type { EntityResolutionCandidate, EntityResolutionResult, EntityResolutionStrategy, KnowledgeEntity } from '../types';
+export interface EntityResolverOptions {
+    strategies?: EntityResolutionStrategy[];
+    mergeThreshold?: number;
+    embed?: (text: string) => Promise<number[]> | number[];
+    custom?: (candidate: KnowledgeEntity, existing: KnowledgeEntity[]) => Promise<EntityResolutionCandidate[]> | EntityResolutionCandidate[];
+}
+/**
+ * Extensible entity resolution. Uncertain matches are returned as candidates
+ * and are never auto-merged below mergeThreshold.
+ */
+export declare class EntityResolver {
+    private readonly strategies;
+    private readonly mergeThreshold;
+    private readonly embed?;
+    private readonly custom?;
+    constructor(options?: EntityResolverOptions);
+    resolve(candidate: KnowledgeEntity, existing: KnowledgeEntity[]): Promise<EntityResolutionResult>;
+}
+export declare function normalizeName(name: string): string;
+//# sourceMappingURL=entity-resolver.d.ts.map

package/dist/resolution/entity-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-resolver.d.ts","sourceRoot":"","sources":["../../src/resolution/entity-resolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,yBAAyB,EACzB,sBAAsB,EACtB,wBAAwB,EACxB,eAAe,EAChB,MAAM,UAAU,CAAC;AAElB,MAAM,WAAW,qBAAqB;IACpC,UAAU,CAAC,EAAE,wBAAwB,EAAE,CAAC;IACxC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,GAAG,MAAM,EAAE,CAAC;IACvD,MAAM,CAAC,EAAE,CACP,SAAS,EAAE,eAAe,EAC1B,QAAQ,EAAE,eAAe,EAAE,KACxB,OAAO,CAAC,yBAAyB,EAAE,CAAC,GAAG,yBAAyB,EAAE,CAAC;CACzE;AAED;;;GAGG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA6B;IACxD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAiC;IACxD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAkC;gBAE9C,OAAO,GAAE,qBAA0B;IAOzC,OAAO,CACX,SAAS,EAAE,eAAe,EAC1B,QAAQ,EAAE,eAAe,EAAE,GAC1B,OAAO,CAAC,sBAAsB,CAAC;CA+DnC;AAgBD,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAOlD"}

package/dist/resolution/entity-resolver.js

@@ -0,0 +1,123 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EntityResolver = void 0;
+exports.normalizeName = normalizeName;
+/**
+ * Extensible entity resolution. Uncertain matches are returned as candidates
+ * and are never auto-merged below mergeThreshold.
+ */
+class EntityResolver {
+    constructor(options = {}) {
+        this.strategies = options.strategies ?? ['exact', 'normalized'];
+        this.mergeThreshold = options.mergeThreshold ?? 0.9;
+        this.embed = options.embed;
+        this.custom = options.custom;
+    }
+    async resolve(candidate, existing) {
+        const candidates = [];
+        for (const strategy of this.strategies) {
+            if (strategy === 'exact') {
+                for (const entity of existing) {
+                    if (entity.id === candidate.id) {
+                        candidates.push({ entity, confidence: 1, strategy: 'exact' });
+                    }
+                    else if (namesMatchExact(entity, candidate)) {
+                        candidates.push({ entity, confidence: 0.99, strategy: 'exact' });
+                    }
+                }
+            }
+            if (strategy === 'normalized') {
+                const candNorm = normalizeName(displayName(candidate));
+                for (const entity of existing) {
+                    const entNorm = normalizeName(displayName(entity));
+                    if (candNorm && entNorm && candNorm === entNorm) {
+                        candidates.push({ entity, confidence: 0.95, strategy: 'normalized' });
+                    }
+                }
+            }
+            if (strategy === 'semantic' && this.embed) {
+                const candVec = await this.embed(displayName(candidate));
+                for (const entity of existing) {
+                    const entVec = await this.embed(displayName(entity));
+                    const sim = cosineSimilarity(candVec, entVec);
+                    if (sim >= 0.8) {
+                        candidates.push({ entity, confidence: sim, strategy: 'semantic' });
+                    }
+                }
+            }
+            if (strategy === 'custom' && this.custom) {
+                candidates.push(...(await this.custom(candidate, existing)));
+            }
+        }
+        // Deduplicate by entity id, keep highest confidence
+        const byId = new Map();
+        for (const c of candidates) {
+            const prev = byId.get(c.entity.id);
+            if (!prev || c.confidence > prev.confidence) {
+                byId.set(c.entity.id, c);
+            }
+        }
+        const unique = [...byId.values()].sort((a, b) => b.confidence - a.confidence);
+        const best = unique[0];
+        if (best && best.confidence >= this.mergeThreshold) {
+            return {
+                merged: {
+                    ...best.entity,
+                    aliases: uniqueAliases(best.entity, candidate),
+                    properties: { ...best.entity.properties, ...candidate.properties },
+                    confidence: best.confidence,
+                },
+                candidates: unique,
+            };
+        }
+        return { candidates: unique };
+    }
+}
+exports.EntityResolver = EntityResolver;
+function displayName(entity) {
+    const name = entity.properties.name ?? entity.properties.title ?? entity.id;
+    return String(name);
+}
+function namesMatchExact(a, b) {
+    const an = displayName(a);
+    const bn = displayName(b);
+    if (an === bn)
+        return true;
+    const aliasesA = a.aliases ?? [];
+    const aliasesB = b.aliases ?? [];
+    return aliasesA.includes(bn) || aliasesB.includes(an);
+}
+function normalizeName(name) {
+    return name
+        .toLowerCase()
+        .replace(/[.,]/g, ' ')
+        .replace(/\b(inc|incorporated|llc|ltd|limited|corp|corporation|co)\b/g, '')
+        .replace(/\s+/g, '')
+        .trim();
+}
+function uniqueAliases(base, incoming) {
+    const set = new Set([
+        ...(base.aliases ?? []),
+        ...(incoming.aliases ?? []),
+        displayName(incoming),
+        displayName(base),
+    ]);
+    set.delete(displayName(base));
+    return [...set].filter(Boolean);
+}
+function cosineSimilarity(a, b) {
+    const len = Math.min(a.length, b.length);
+    if (len === 0)
+        return 0;
+    let dot = 0;
+    let na = 0;
+    let nb = 0;
+    for (let i = 0; i < len; i++) {
+        dot += a[i] * b[i];
+        na += a[i] * a[i];
+        nb += b[i] * b[i];
+    }
+    if (na === 0 || nb === 0)
+        return 0;
+    return dot / (Math.sqrt(na) * Math.sqrt(nb));
+}

package/dist/security/authorizer.d.ts

@@ -0,0 +1,27 @@
+import type { KnowledgeAuthorizer, KnowledgeScope } from '../types';
+/**
+ * Default authorizer: require tenantId and enforce tenant equality.
+ */
+export declare class TenantKnowledgeAuthorizer implements KnowledgeAuthorizer {
+    private readonly expectedTenantId?;
+    constructor(expectedTenantId?: string | undefined);
+    canAccess(scope: KnowledgeScope, _action: 'read' | 'write', _resource: {
+        kind: 'entity' | 'relation' | 'fact' | 'source';
+        id?: string;
+        type?: string;
+    }): boolean;
+}
+/**
+ * Adapts a CASL-shaped can(action, subject) without depending on @hazeljs/casl.
+ */
+export declare function createCaslKnowledgeAuthorizer(can: (action: string, subject: string | {
+    __typename?: string;
+    id?: string;
+    tenantId?: string;
+}) => boolean): KnowledgeAuthorizer;
+export declare function assertAuthorized(authorizer: KnowledgeAuthorizer | undefined, scope: KnowledgeScope, action: 'read' | 'write', resource: {
+    kind: 'entity' | 'relation' | 'fact' | 'source';
+    id?: string;
+    type?: string;
+}): Promise<void>;
+//# sourceMappingURL=authorizer.d.ts.map

package/dist/security/authorizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorizer.d.ts","sourceRoot":"","sources":["../../src/security/authorizer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAGpE;;GAEG;AACH,qBAAa,yBAA0B,YAAW,mBAAmB;IACvD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC;gBAAjB,gBAAgB,CAAC,EAAE,MAAM,YAAA;IAEtD,SAAS,CACP,KAAK,EAAE,cAAc,EACrB,OAAO,EAAE,MAAM,GAAG,OAAO,EACzB,SAAS,EAAE;QAAE,IAAI,EAAE,QAAQ,GAAG,UAAU,GAAG,MAAM,GAAG,QAAQ,CAAC;QAAC,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GACzF,OAAO;CAOX;AAED;;GAEG;AACH,wBAAgB,6BAA6B,CAC3C,GAAG,EAAE,CACH,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,GAAG;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,KACtE,OAAO,GACX,mBAAmB,CAoBrB;AAED,wBAAsB,gBAAgB,CACpC,UAAU,EAAE,mBAAmB,GAAG,SAAS,EAC3C,KAAK,EAAE,cAAc,EACrB,MAAM,EAAE,MAAM,GAAG,OAAO,EACxB,QAAQ,EAAE;IAAE,IAAI,EAAE,QAAQ,GAAG,UAAU,GAAG,MAAM,GAAG,QAAQ,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GACxF,OAAO,CAAC,IAAI,CAAC,CASf"}

package/dist/security/authorizer.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TenantKnowledgeAuthorizer = void 0;
+exports.createCaslKnowledgeAuthorizer = createCaslKnowledgeAuthorizer;
+exports.assertAuthorized = assertAuthorized;
+const kag_error_1 = require("../errors/kag.error");
+/**
+ * Default authorizer: require tenantId and enforce tenant equality.
+ */
+class TenantKnowledgeAuthorizer {
+    constructor(expectedTenantId) {
+        this.expectedTenantId = expectedTenantId;
+    }
+    canAccess(scope, _action, _resource) {
+        if (!scope.tenantId)
+            return false;
+        if (this.expectedTenantId && scope.tenantId !== this.expectedTenantId) {
+            return false;
+        }
+        return true;
+    }
+}
+exports.TenantKnowledgeAuthorizer = TenantKnowledgeAuthorizer;
+/**
+ * Adapts a CASL-shaped can(action, subject) without depending on @hazeljs/casl.
+ */
+function createCaslKnowledgeAuthorizer(can) {
+    return {
+        canAccess(scope, action, resource) {
+            if (!scope.tenantId)
+                return false;
+            const subject = resource.kind === 'source'
+                ? { __typename: 'KnowledgeSource', id: resource.id, tenantId: scope.tenantId }
+                : {
+                    __typename: resource.kind === 'entity'
+                        ? 'KnowledgeEntity'
+                        : resource.kind === 'relation'
+                            ? 'KnowledgeRelation'
+                            : 'KnowledgeFact',
+                    id: resource.id,
+                    tenantId: scope.tenantId,
+                };
+            return can(action === 'read' ? 'read' : 'update', subject);
+        },
+    };
+}
+async function assertAuthorized(authorizer, scope, action, resource) {
+    if (!scope.tenantId) {
+        throw kag_error_1.KagError.tenantRequired();
+    }
+    if (!authorizer)
+        return;
+    const ok = await authorizer.canAccess(scope, action, resource);
+    if (!ok) {
+        throw kag_error_1.KagError.accessDenied(`${resource.kind}:${resource.id ?? resource.type ?? '*'}`);
+    }
+}

package/dist/stores/in-memory-knowledge.store.d.ts

@@ -0,0 +1,22 @@
+import type { ContradictionPolicy, KnowledgeEntity, KnowledgeFact, KnowledgeQuery, KnowledgeRelation, KnowledgeResult, KnowledgeScope, KnowledgeStore, TraversalOptions, TraversalResult } from '../types';
+/**
+ * Tenant-partitioned in-memory knowledge store for development and tests.
+ */
+export declare class InMemoryKnowledgeStore implements KnowledgeStore {
+    private readonly contradictionPolicy;
+    private readonly partitions;
+    constructor(contradictionPolicy?: ContradictionPolicy);
+    private partition;
+    upsertEntity(scope: KnowledgeScope, entity: KnowledgeEntity): Promise<void>;
+    upsertRelation(scope: KnowledgeScope, relation: KnowledgeRelation): Promise<void>;
+    upsertFact(scope: KnowledgeScope, fact: KnowledgeFact): Promise<{
+        contradictions: KnowledgeFact[];
+    }>;
+    getEntity(scope: KnowledgeScope, id: string): Promise<KnowledgeEntity | null>;
+    query(scope: KnowledgeScope, query: KnowledgeQuery): Promise<KnowledgeResult>;
+    traverse(scope: KnowledgeScope, seedIds: string[], options?: TraversalOptions): Promise<TraversalResult>;
+    listEntities(scope: KnowledgeScope): Promise<KnowledgeEntity[]>;
+    clear(scope: KnowledgeScope): Promise<void>;
+    private groupContradictions;
+}
+//# sourceMappingURL=in-memory-knowledge.store.d.ts.map

package/dist/stores/in-memory-knowledge.store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-memory-knowledge.store.d.ts","sourceRoot":"","sources":["../../src/stores/in-memory-knowledge.store.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,mBAAmB,EACnB,eAAe,EACf,aAAa,EACb,cAAc,EACd,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,cAAc,EACd,gBAAgB,EAChB,eAAe,EAChB,MAAM,UAAU,CAAC;AAmBlB;;GAEG;AACH,qBAAa,sBAAuB,YAAW,cAAc;IAG/C,OAAO,CAAC,QAAQ,CAAC,mBAAmB;IAFhD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAgC;gBAE9B,mBAAmB,GAAE,mBAA4B;IAE9E,OAAO,CAAC,SAAS;IAeX,YAAY,CAAC,KAAK,EAAE,cAAc,EAAE,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAK3E,cAAc,CAAC,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAWjF,UAAU,CACd,KAAK,EAAE,cAAc,EACrB,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC;QAAE,cAAc,EAAE,aAAa,EAAE,CAAA;KAAE,CAAC;IA4BzC,SAAS,CAAC,KAAK,EAAE,cAAc,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAI7E,KAAK,CAAC,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC;IAoC7E,QAAQ,CACZ,KAAK,EAAE,cAAc,EACrB,OAAO,EAAE,MAAM,EAAE,EACjB,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,eAAe,CAAC;IAqDrB,YAAY,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAI/D,KAAK,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAIjD,OAAO,CAAC,mBAAmB;CAqB5B"}

package/dist/stores/in-memory-knowledge.store.js

@@ -0,0 +1,186 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InMemoryKnowledgeStore = void 0;
+const crypto_1 = require("crypto");
+const kag_error_1 = require("../errors/kag.error");
+const temporal_1 = require("../temporal");
+const confidence_1 = require("../confidence");
+function scopeKey(scope) {
+    if (!scope.tenantId) {
+        throw kag_error_1.KagError.tenantRequired();
+    }
+    return `${scope.tenantId}::${scope.graph ?? 'default'}`;
+}
+/**
+ * Tenant-partitioned in-memory knowledge store for development and tests.
+ */
+class InMemoryKnowledgeStore {
+    constructor(contradictionPolicy = 'rank') {
+        this.contradictionPolicy = contradictionPolicy;
+        this.partitions = new Map();
+    }
+    partition(scope) {
+        const key = scopeKey(scope);
+        let part = this.partitions.get(key);
+        if (!part) {
+            part = {
+                entities: new Map(),
+                relations: new Map(),
+                facts: [],
+                adjacency: new Map(),
+            };
+            this.partitions.set(key, part);
+        }
+        return part;
+    }
+    async upsertEntity(scope, entity) {
+        const part = this.partition(scope);
+        part.entities.set(entity.id, { ...entity, properties: { ...entity.properties } });
+    }
+    async upsertRelation(scope, relation) {
+        const part = this.partition(scope);
+        const id = relation.id || `${relation.from}:${relation.type}:${relation.to}`;
+        const stored = { ...relation, id };
+        part.relations.set(id, stored);
+        if (!part.adjacency.has(relation.from))
+            part.adjacency.set(relation.from, new Set());
+        if (!part.adjacency.has(relation.to))
+            part.adjacency.set(relation.to, new Set());
+        part.adjacency.get(relation.from).add(relation.to);
+        part.adjacency.get(relation.to).add(relation.from);
+    }
+    async upsertFact(scope, fact) {
+        const part = this.partition(scope);
+        const stored = {
+            ...fact,
+            id: fact.id ?? (0, crypto_1.randomUUID)(),
+            createdAt: fact.createdAt ?? new Date().toISOString(),
+            confidence: fact.confidence ?? 1,
+        };
+        const contradictions = part.facts.filter((existing) => existing.subject === stored.subject &&
+            existing.predicate === stored.predicate &&
+            (0, temporal_1.factsOverlap)(existing, stored) &&
+            !(0, temporal_1.objectsEqual)(existing.object, stored.object));
+        if (contradictions.length > 0 && this.contradictionPolicy === 'reject') {
+            throw kag_error_1.KagError.conflict('Contradicting fact rejected by policy', {
+                fact: stored,
+                contradictions,
+            });
+        }
+        part.facts.push(stored);
+        return { contradictions };
+    }
+    async getEntity(scope, id) {
+        return this.partition(scope).entities.get(id) ?? null;
+    }
+    async query(scope, query) {
+        const part = this.partition(scope);
+        let entities = [...part.entities.values()];
+        if (query.entityIds?.length) {
+            const set = new Set(query.entityIds);
+            entities = entities.filter((e) => set.has(e.id));
+        }
+        if (query.types?.length) {
+            const set = new Set(query.types);
+            entities = entities.filter((e) => set.has(e.type));
+        }
+        let facts = part.facts.filter((f) => {
+            if (query.entityIds?.length && !query.entityIds.includes(f.subject))
+                return false;
+            if (query.predicate && f.predicate !== query.predicate)
+                return false;
+            if (query.currentOnly || query.asOf) {
+                return (0, temporal_1.isFactValidAt)(f, query.asOf);
+            }
+            return true;
+        });
+        if (query.limit) {
+            facts = facts.slice(0, query.limit);
+            entities = entities.slice(0, query.limit);
+        }
+        const relations = [...part.relations.values()].filter((r) => {
+            if (!query.entityIds?.length)
+                return true;
+            return query.entityIds.includes(r.from) || query.entityIds.includes(r.to);
+        });
+        const contradictions = this.groupContradictions(facts);
+        return { entities, relations, facts, contradictions };
+    }
+    async traverse(scope, seedIds, options = {}) {
+        const part = this.partition(scope);
+        const depth = options.depth ?? 2;
+        const visited = new Set();
+        const queue = seedIds.map((id) => ({ id, d: 0 }));
+        const entityIds = new Set();
+        const relationIds = new Set();
+        while (queue.length > 0) {
+            const { id, d } = queue.shift();
+            if (visited.has(id))
+                continue;
+            visited.add(id);
+            entityIds.add(id);
+            if (d >= depth)
+                continue;
+            for (const rel of part.relations.values()) {
+                if (options.relationTypes && !options.relationTypes.includes(rel.type)) {
+                    continue;
+                }
+                let neighbor = null;
+                if (rel.from === id)
+                    neighbor = rel.to;
+                else if (rel.to === id)
+                    neighbor = rel.from;
+                if (!neighbor)
+                    continue;
+                relationIds.add(rel.id);
+                if (!visited.has(neighbor)) {
+                    queue.push({ id: neighbor, d: d + 1 });
+                }
+            }
+        }
+        const entities = [...entityIds]
+            .map((id) => part.entities.get(id))
+            .filter((e) => Boolean(e));
+        const relations = [...relationIds]
+            .map((id) => part.relations.get(id))
+            .filter((r) => Boolean(r));
+        const facts = part.facts.filter((f) => entityIds.has(f.subject) && (0, temporal_1.isFactValidAt)(f, options.asOf));
+        const confidences = [
+            ...relations.map((r) => r.confidence ?? 1),
+            ...facts.map((f) => f.confidence ?? 1),
+        ];
+        return {
+            entities,
+            relations,
+            facts,
+            confidence: (0, confidence_1.aggregateConfidence)(confidences, 'min'),
+        };
+    }
+    async listEntities(scope) {
+        return [...this.partition(scope).entities.values()];
+    }
+    async clear(scope) {
+        this.partitions.delete(scopeKey(scope));
+    }
+    groupContradictions(facts) {
+        const groups = [];
+        const used = new Set();
+        for (const fact of facts) {
+            if (!fact.id || used.has(fact.id))
+                continue;
+            const sameSlot = facts.filter((other) => other.subject === fact.subject &&
+                other.predicate === fact.predicate &&
+                (0, temporal_1.factsOverlap)(fact, other));
+            const distinctObjects = new Set(sameSlot.map((f) => JSON.stringify(f.object)));
+            if (sameSlot.length > 1 && distinctObjects.size > 1) {
+                for (const g of sameSlot) {
+                    if (g.id)
+                        used.add(g.id);
+                }
+                groups.push(sameSlot);
+            }
+        }
+        return groups;
+    }
+}
+exports.InMemoryKnowledgeStore = InMemoryKnowledgeStore;

package/dist/temporal.d.ts

@@ -0,0 +1,7 @@
+import type { KnowledgeFact } from './types';
+export declare function toDate(value: Date | string | undefined): Date | undefined;
+export declare function isFactValidAt(fact: KnowledgeFact, asOf?: Date | string): boolean;
+export declare function factsOverlap(a: KnowledgeFact, b: KnowledgeFact): boolean;
+export declare function objectsEqual(a: unknown, b: unknown): boolean;
+export declare function changesBetween(facts: KnowledgeFact[], from: Date | string, to: Date | string): KnowledgeFact[];
+//# sourceMappingURL=temporal.d.ts.map

package/dist/temporal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"temporal.d.ts","sourceRoot":"","sources":["../src/temporal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C,wBAAgB,MAAM,CAAC,KAAK,EAAE,IAAI,GAAG,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,SAAS,CAKzE;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,aAAa,EAAE,IAAI,CAAC,EAAE,IAAI,GAAG,MAAM,GAAG,OAAO,CAgBhF;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,aAAa,GAAG,OAAO,CAMxE;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CAE5D;AAED,wBAAgB,cAAc,CAC5B,KAAK,EAAE,aAAa,EAAE,EACtB,IAAI,EAAE,IAAI,GAAG,MAAM,EACnB,EAAE,EAAE,IAAI,GAAG,MAAM,GAChB,aAAa,EAAE,CAYjB"}

package/dist/temporal.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toDate = toDate;
+exports.isFactValidAt = isFactValidAt;
+exports.factsOverlap = factsOverlap;
+exports.objectsEqual = objectsEqual;
+exports.changesBetween = changesBetween;
+function toDate(value) {
+    if (value === undefined)
+        return undefined;
+    if (value instanceof Date)
+        return value;
+    const d = new Date(value);
+    return Number.isNaN(d.getTime()) ? undefined : d;
+}
+function isFactValidAt(fact, asOf) {
+    if (asOf === undefined) {
+        // current: valid if no validUntil or validUntil in the future
+        const until = toDate(fact.validUntil);
+        if (until && until.getTime() < Date.now())
+            return false;
+        const from = toDate(fact.validFrom);
+        if (from && from.getTime() > Date.now())
+            return false;
+        return true;
+    }
+    const at = toDate(asOf);
+    if (!at)
+        return true;
+    const from = toDate(fact.validFrom);
+    const until = toDate(fact.validUntil);
+    if (from && at.getTime() < from.getTime())
+        return false;
+    if (until && at.getTime() > until.getTime())
+        return false;
+    return true;
+}
+function factsOverlap(a, b) {
+    const aFrom = toDate(a.validFrom)?.getTime() ?? Number.NEGATIVE_INFINITY;
+    const aUntil = toDate(a.validUntil)?.getTime() ?? Number.POSITIVE_INFINITY;
+    const bFrom = toDate(b.validFrom)?.getTime() ?? Number.NEGATIVE_INFINITY;
+    const bUntil = toDate(b.validUntil)?.getTime() ?? Number.POSITIVE_INFINITY;
+    return aFrom <= bUntil && bFrom <= aUntil;
+}
+function objectsEqual(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+function changesBetween(facts, from, to) {
+    const start = toDate(from)?.getTime() ?? 0;
+    const end = toDate(to)?.getTime() ?? Date.now();
+    return facts.filter((f) => {
+        const vf = toDate(f.validFrom)?.getTime();
+        const vu = toDate(f.validUntil)?.getTime();
+        const created = toDate(f.createdAt)?.getTime();
+        if (vf !== undefined && vf >= start && vf <= end)
+            return true;
+        if (vu !== undefined && vu >= start && vu <= end)
+            return true;
+        if (created !== undefined && created >= start && created <= end)
+            return true;
+        return false;
+    });
+}