@eddacraft/kindling-core 0.1.0

package/dist/export/restore.js

@@ -0,0 +1,149 @@
+/**
+ * Service-level import coordination
+ *
+ * Provides high-level import API for restoring from export bundles.
+ */
+import { validateBundle } from './bundle.js';
+/**
+ * Restore from export bundle
+ *
+ * Coordinates import with validation and error handling.
+ *
+ * @param store - Import store
+ * @param bundle - Export bundle to restore
+ * @param options - Import options
+ * @returns Import result with counts and errors
+ */
+export function restoreFromBundle(store, bundle, options = {}) {
+    const { skipValidation = false, dryRun = false } = options;
+    // Validate bundle structure
+    if (!skipValidation) {
+        const validation = validateBundle(bundle);
+        if (!validation.valid) {
+            return {
+                observations: 0,
+                capsules: 0,
+                summaries: 0,
+                pins: 0,
+                errors: validation.errors,
+                dryRun,
+            };
+        }
+    }
+    // Dry run: validate only, don't import
+    if (dryRun) {
+        return {
+            observations: bundle.dataset.observations.length,
+            capsules: bundle.dataset.capsules.length,
+            summaries: bundle.dataset.summaries.length,
+            pins: bundle.dataset.pins.length,
+            errors: [],
+            dryRun: true,
+        };
+    }
+    // Import dataset
+    const result = store.importDatabase(bundle.dataset);
+    return {
+        ...result,
+        dryRun: false,
+    };
+}
+/**
+ * Merge multiple export bundles
+ *
+ * Combines datasets from multiple bundles into a single bundle.
+ * Useful for consolidating exports from different sources.
+ *
+ * @param bundles - Bundles to merge
+ * @param metadata - Optional metadata for merged bundle
+ * @returns Merged bundle
+ */
+export function mergeBundles(bundles, metadata) {
+    if (bundles.length === 0) {
+        throw new Error('At least one bundle required for merge');
+    }
+    // Validate all bundles
+    for (const bundle of bundles) {
+        const validation = validateBundle(bundle);
+        if (!validation.valid) {
+            throw new Error(`Invalid bundle: ${validation.errors.join(', ')}`);
+        }
+    }
+    // Merge datasets
+    const merged = {
+        observations: [],
+        capsules: [],
+        summaries: [],
+        pins: [],
+    };
+    for (const bundle of bundles) {
+        merged.observations.push(...bundle.dataset.observations);
+        merged.capsules.push(...bundle.dataset.capsules);
+        merged.summaries.push(...bundle.dataset.summaries);
+        merged.pins.push(...bundle.dataset.pins);
+    }
+    // Deduplicate by ID
+    const deduped = {
+        observations: deduplicateById(merged.observations),
+        capsules: deduplicateById(merged.capsules),
+        summaries: deduplicateById(merged.summaries),
+        pins: deduplicateById(merged.pins),
+    };
+    return {
+        bundleVersion: '1.0',
+        exportedAt: Date.now(),
+        metadata: metadata || {
+            description: `Merged from ${bundles.length} bundles`,
+        },
+        dataset: {
+            version: '1.0',
+            exportedAt: Date.now(),
+            ...deduped,
+        },
+    };
+}
+/**
+ * Deduplicate entities by ID
+ *
+ * Keeps first occurrence of each ID.
+ *
+ * @param entities - Entities to deduplicate
+ * @returns Deduplicated entities
+ */
+function deduplicateById(entities) {
+    const seen = new Set();
+    const deduped = [];
+    for (const entity of entities) {
+        if (!entity.id)
+            continue;
+        if (!seen.has(entity.id)) {
+            seen.add(entity.id);
+            deduped.push(entity);
+        }
+    }
+    return deduped;
+}
+/**
+ * Compare two bundles for differences
+ *
+ * @param bundle1 - First bundle
+ * @param bundle2 - Second bundle
+ * @returns Difference summary
+ */
+export function compareBundles(bundle1, bundle2) {
+    const compareArrays = (arr1, arr2) => {
+        const ids1 = new Set(arr1.map(e => e.id).filter(Boolean));
+        const ids2 = new Set(arr2.map(e => e.id).filter(Boolean));
+        const common = new Set([...ids1].filter(id => ids2.has(id)));
+        const added = ids2.size - common.size;
+        const removed = ids1.size - common.size;
+        return { added, removed, common: common.size };
+    };
+    return {
+        observations: compareArrays(bundle1.dataset.observations, bundle2.dataset.observations),
+        capsules: compareArrays(bundle1.dataset.capsules, bundle2.dataset.capsules),
+        summaries: compareArrays(bundle1.dataset.summaries, bundle2.dataset.summaries),
+        pins: compareArrays(bundle1.dataset.pins, bundle2.dataset.pins),
+    };
+}
+//# sourceMappingURL=restore.js.map

package/dist/export/restore.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Kindling Core
+ *
+ * Domain model, capsule lifecycle, and retrieval orchestration.
+ */
+export * from './types/index.js';
+export * from './validation/index.js';
+export * from './capsule/index.js';
+export * from './retrieval/index.js';
+export * from './export/index.js';
+export * from './service/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,cAAc,kBAAkB,CAAC;AAGjC,cAAc,uBAAuB,CAAC;AAGtC,cAAc,oBAAoB,CAAC;AAGnC,cAAc,sBAAsB,CAAC;AAGrC,cAAc,mBAAmB,CAAC;AAGlC,cAAc,oBAAoB,CAAC"}

package/dist/index.js

@@ -0,0 +1,18 @@
+/**
+ * Kindling Core
+ *
+ * Domain model, capsule lifecycle, and retrieval orchestration.
+ */
+// Re-export all types
+export * from './types/index.js';
+// Re-export all validation functions
+export * from './validation/index.js';
+// Re-export capsule lifecycle
+export * from './capsule/index.js';
+// Re-export retrieval orchestration
+export * from './retrieval/index.js';
+// Re-export export/import coordination
+export * from './export/index.js';
+// Re-export service orchestration
+export * from './service/index.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,sBAAsB;AACtB,cAAc,kBAAkB,CAAC;AAEjC,qCAAqC;AACrC,cAAc,uBAAuB,CAAC;AAEtC,8BAA8B;AAC9B,cAAc,oBAAoB,CAAC;AAEnC,oCAAoC;AACpC,cAAc,sBAAsB,CAAC;AAErC,uCAAuC;AACvC,cAAc,mBAAmB,CAAC;AAElC,kCAAkC;AAClC,cAAc,oBAAoB,CAAC"}

package/dist/retrieval/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Retrieval orchestration
+ *
+ * Combines pins, summaries, and provider candidates into unified retrieval results.
+ */
+export * from './orchestrator.js';
+export * from './tiering.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/retrieval/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/retrieval/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC"}

package/dist/retrieval/index.js

@@ -0,0 +1,8 @@
+/**
+ * Retrieval orchestration
+ *
+ * Combines pins, summaries, and provider candidates into unified retrieval results.
+ */
+export * from './orchestrator.js';
+export * from './tiering.js';
+//# sourceMappingURL=index.js.map

package/dist/retrieval/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/retrieval/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC"}

package/dist/retrieval/orchestrator.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Retrieval orchestrator
+ *
+ * Combines pins, summaries, and provider candidates into a unified retrieval response.
+ */
+import type { RetrieveOptions, RetrieveResult, RetrievalProvider } from '../types/retrieval.js';
+import type { Pin, Observation, Summary, ID } from '../types/index.js';
+/**
+ * Store interface for retrieval operations
+ */
+export interface RetrievalStore {
+    /**
+     * List active pins for a scope
+     */
+    listActivePins(scopeIds?: Partial<Record<string, string>>, now?: number): Pin[];
+    /**
+     * Get observation by ID
+     */
+    getObservationById(observationId: ID): Observation | undefined;
+    /**
+     * Get summary by ID
+     */
+    getSummaryById(summaryId: ID): Summary | undefined;
+    /**
+     * Get open capsule for session
+     */
+    getOpenCapsuleForSession(sessionId: string): {
+        id: ID;
+        summaryId?: ID;
+    } | undefined;
+    /**
+     * Get latest summary for capsule
+     */
+    getLatestSummaryForCapsule(capsuleId: ID): Summary | undefined;
+}
+/**
+ * Retrieve relevant context for a query
+ *
+ * Orchestrates retrieval by combining:
+ * 1. Active pins (non-evictable, always included)
+ * 2. Current session summary (non-evictable if exists)
+ * 3. Provider candidates (ranked, budget-limited)
+ *
+ * @param store - Retrieval store
+ * @param provider - Retrieval provider
+ * @param options - Retrieval options
+ * @returns Retrieval result with pins, summary, and candidates
+ */
+export declare function retrieve(store: RetrievalStore, provider: RetrievalProvider, options: RetrieveOptions): Promise<RetrieveResult>;
+//# sourceMappingURL=orchestrator.d.ts.map

package/dist/retrieval/orchestrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../../src/retrieval/orchestrator.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EAGd,iBAAiB,EAClB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,GAAG,EAAE,WAAW,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,mBAAmB,CAAC;AAEvE;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,cAAc,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,GAAG,EAAE,CAAC;IAEhF;;OAEG;IACH,kBAAkB,CAAC,aAAa,EAAE,EAAE,GAAG,WAAW,GAAG,SAAS,CAAC;IAE/D;;OAEG;IACH,cAAc,CAAC,SAAS,EAAE,EAAE,GAAG,OAAO,GAAG,SAAS,CAAC;IAEnD;;OAEG;IACH,wBAAwB,CAAC,SAAS,EAAE,MAAM,GAAG;QAAE,EAAE,EAAE,EAAE,CAAC;QAAC,SAAS,CAAC,EAAE,EAAE,CAAA;KAAE,GAAG,SAAS,CAAC;IAEpF;;OAEG;IACH,0BAA0B,CAAC,SAAS,EAAE,EAAE,GAAG,OAAO,GAAG,SAAS,CAAC;CAChE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,QAAQ,CAC5B,KAAK,EAAE,cAAc,EACrB,QAAQ,EAAE,iBAAiB,EAC3B,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,cAAc,CAAC,CAmFzB"}

package/dist/retrieval/orchestrator.js

@@ -0,0 +1,86 @@
+/**
+ * Retrieval orchestrator
+ *
+ * Combines pins, summaries, and provider candidates into a unified retrieval response.
+ */
+/**
+ * Retrieve relevant context for a query
+ *
+ * Orchestrates retrieval by combining:
+ * 1. Active pins (non-evictable, always included)
+ * 2. Current session summary (non-evictable if exists)
+ * 3. Provider candidates (ranked, budget-limited)
+ *
+ * @param store - Retrieval store
+ * @param provider - Retrieval provider
+ * @param options - Retrieval options
+ * @returns Retrieval result with pins, summary, and candidates
+ */
+export async function retrieve(store, provider, options) {
+    const { query, scopeIds, maxCandidates = 10, includeRedacted = false, } = options;
+    const now = Date.now();
+    // Step 1: Fetch active pins for scope
+    const pins = store.listActivePins(scopeIds, now);
+    // Step 2: Resolve pins to their targets
+    const pinResults = [];
+    const pinnedIds = new Set();
+    for (const pin of pins) {
+        let target;
+        if (pin.targetType === 'observation') {
+            target = store.getObservationById(pin.targetId);
+        }
+        else if (pin.targetType === 'summary') {
+            target = store.getSummaryById(pin.targetId);
+        }
+        if (target) {
+            // Skip redacted unless explicitly requested
+            if ('redacted' in target && target.redacted && !includeRedacted) {
+                continue;
+            }
+            pinResults.push({ pin, target });
+            pinnedIds.add(target.id);
+        }
+    }
+    // Step 3: Get current session summary (non-evictable)
+    let currentSummary;
+    if (scopeIds.sessionId) {
+        const capsule = store.getOpenCapsuleForSession(scopeIds.sessionId);
+        if (capsule) {
+            const summary = store.getLatestSummaryForCapsule(capsule.id);
+            if (summary) {
+                currentSummary = summary;
+                pinnedIds.add(summary.id);
+            }
+        }
+    }
+    // Step 4: Get provider candidates (exclude pinned and current summary)
+    const providerResults = await provider.search({
+        query,
+        scopeIds,
+        maxResults: maxCandidates,
+        excludeIds: Array.from(pinnedIds),
+        includeRedacted,
+    });
+    // Step 5: Convert provider results to candidates
+    const candidates = providerResults.map(result => ({
+        entity: result.entity,
+        score: result.score,
+        matchContext: result.matchContext,
+    }));
+    // Step 6: Build provenance
+    const provenance = {
+        query,
+        scopeIds,
+        totalCandidates: providerResults.length,
+        returnedCandidates: candidates.length,
+        truncatedDueToTokenBudget: false, // Token budgeting not implemented in v0.1
+        providerUsed: provider.name,
+    };
+    return {
+        pins: pinResults,
+        currentSummary,
+        candidates,
+        provenance,
+    };
+}
+//# sourceMappingURL=orchestrator.js.map

package/dist/retrieval/orchestrator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator.js","sourceRoot":"","sources":["../../src/retrieval/orchestrator.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAyCH;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,KAAqB,EACrB,QAA2B,EAC3B,OAAwB;IAExB,MAAM,EACJ,KAAK,EACL,QAAQ,EACR,aAAa,GAAG,EAAE,EAClB,eAAe,GAAG,KAAK,GACxB,GAAG,OAAO,CAAC;IAEZ,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAEvB,sCAAsC;IACtC,MAAM,IAAI,GAAG,KAAK,CAAC,cAAc,CAAC,QAA2C,EAAE,GAAG,CAAC,CAAC;IAEpF,wCAAwC;IACxC,MAAM,UAAU,GAAgB,EAAE,CAAC;IACnC,MAAM,SAAS,GAAG,IAAI,GAAG,EAAM,CAAC;IAEhC,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,IAAI,MAAyC,CAAC;QAE9C,IAAI,GAAG,CAAC,UAAU,KAAK,aAAa,EAAE,CAAC;YACrC,MAAM,GAAG,KAAK,CAAC,kBAAkB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAClD,CAAC;aAAM,IAAI,GAAG,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;YACxC,MAAM,GAAG,KAAK,CAAC,cAAc,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC9C,CAAC;QAED,IAAI,MAAM,EAAE,CAAC;YACX,4CAA4C;YAC5C,IAAI,UAAU,IAAI,MAAM,IAAI,MAAM,CAAC,QAAQ,IAAI,CAAC,eAAe,EAAE,CAAC;gBAChE,SAAS;YACX,CAAC;YAED,UAAU,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,CAAC;YACjC,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAC3B,CAAC;IACH,CAAC;IAED,sDAAsD;IACtD,IAAI,cAAmC,CAAC;IAExC,IAAI,QAAQ,CAAC,SAAS,EAAE,CAAC;QACvB,MAAM,OAAO,GAAG,KAAK,CAAC,wBAAwB,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;QACnE,IAAI,OAAO,EAAE,CAAC;YACZ,MAAM,OAAO,GAAG,KAAK,CAAC,0BAA0B,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;YAC7D,IAAI,OAAO,EAAE,CAAC;gBACZ,cAAc,GAAG,OAAO,CAAC;gBACzB,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;YAC5B,CAAC;QACH,CAAC;IACH,CAAC;IAED,uEAAuE;IACvE,MAAM,eAAe,GAAG,MAAM,QAAQ,CAAC,MAAM,CAAC;QAC5C,KAAK;QACL,QAAQ;QACR,UAAU,EAAE,aAAa;QACzB,UAAU,EAAE,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC;QACjC,eAAe;KAChB,CAAC,CAAC;IAEH,iDAAiD;IACjD,MAAM,UAAU,GAAsB,eAAe,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACnE,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,YAAY,EAAE,MAAM,CAAC,YAAY;KAClC,CAAC,CAAC,CAAC;IAEJ,2BAA2B;IAC3B,MAAM,UAAU,GAAG;QACjB,KAAK;QACL,QAAQ;QACR,eAAe,EAAE,eAAe,CAAC,MAAM;QACvC,kBAAkB,EAAE,UAAU,CAAC,MAAM;QACrC,yBAAyB,EAAE,KAAK,EAAE,0CAA0C;QAC5E,YAAY,EAAE,QAAQ,CAAC,IAAI;KAC5B,CAAC;IAEF,OAAO;QACL,IAAI,EAAE,UAAU;QAChB,cAAc;QACd,UAAU;QACV,UAAU;KACX,CAAC;AACJ,CAAC"}

package/dist/retrieval/tiering.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Retrieval tiering utilities
+ *
+ * Implements tiering rules for retrieval results:
+ * - Tier 0 (non-evictable): Pins and current session summary
+ * - Tier 1 (evictable): Provider candidates
+ */
+import type { PinResult, CandidateResult } from '../types/retrieval.js';
+import type { Summary } from '../types/summary.js';
+/**
+ * Tiering levels
+ */
+export declare enum Tier {
+    /** Non-evictable: pins and current summary */
+    PINNED = 0,
+    /** Evictable: provider candidates */
+    CANDIDATE = 1
+}
+/**
+ * Result with tier assignment
+ */
+export interface TieredResult {
+    tier: Tier;
+    content: string;
+    id: string;
+}
+/**
+ * Assign tiers to retrieval results
+ *
+ * Tier 0 (non-evictable):
+ * - Active pins
+ * - Current session summary
+ *
+ * Tier 1 (evictable):
+ * - Provider candidates
+ *
+ * @param pins - Pin results
+ * @param currentSummary - Current session summary
+ * @param candidates - Provider candidates
+ * @returns Tiered results in priority order
+ */
+export declare function assignTiers(pins: PinResult[], currentSummary: Summary | undefined, candidates: CandidateResult[]): TieredResult[];
+/**
+ * Filter tiered results by token budget
+ *
+ * Ensures tier 0 (non-evictable) items are always included.
+ * Tier 1 items are included until budget exhausted.
+ *
+ * @param tiered - Tiered results
+ * @param tokenBudget - Maximum tokens to include
+ * @param estimateTokens - Function to estimate tokens for content
+ * @returns Filtered results that fit within budget
+ */
+export declare function filterByTokenBudget(tiered: TieredResult[], tokenBudget: number, estimateTokens?: (content: string) => number): TieredResult[];
+/**
+ * Simple token estimation (characters / 4)
+ *
+ * Rough approximation: ~4 characters per token on average
+ *
+ * @param content - Content to estimate
+ * @returns Estimated token count
+ */
+export declare function estimateTokensSimple(content: string): number;
+/**
+ * Check if tier 0 results exceed token budget
+ *
+ * Returns true if non-evictable items (pins + current summary) exceed budget.
+ * This is a warning condition - tier 0 items are always included.
+ *
+ * @param tiered - Tiered results
+ * @param tokenBudget - Token budget
+ * @param estimateTokens - Token estimation function
+ * @returns True if tier 0 exceeds budget
+ */
+export declare function tier0ExceedsBudget(tiered: TieredResult[], tokenBudget: number, estimateTokens?: (content: string) => number): boolean;
+//# sourceMappingURL=tiering.d.ts.map

package/dist/retrieval/tiering.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tiering.d.ts","sourceRoot":"","sources":["../../src/retrieval/tiering.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAEnD;;GAEG;AACH,oBAAY,IAAI;IACd,8CAA8C;IAC9C,MAAM,IAAI;IACV,qCAAqC;IACrC,SAAS,IAAI;CACd;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,IAAI,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,SAAS,EAAE,EACjB,cAAc,EAAE,OAAO,GAAG,SAAS,EACnC,UAAU,EAAE,eAAe,EAAE,GAC5B,YAAY,EAAE,CA+BhB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,YAAY,EAAE,EACtB,WAAW,EAAE,MAAM,EACnB,cAAc,GAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAA6B,GACjE,YAAY,EAAE,CAsBhB;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,YAAY,EAAE,EACtB,WAAW,EAAE,MAAM,EACnB,cAAc,GAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAA6B,GACjE,OAAO,CAUT"}

package/dist/retrieval/tiering.js

@@ -0,0 +1,122 @@
+/**
+ * Retrieval tiering utilities
+ *
+ * Implements tiering rules for retrieval results:
+ * - Tier 0 (non-evictable): Pins and current session summary
+ * - Tier 1 (evictable): Provider candidates
+ */
+/**
+ * Tiering levels
+ */
+export var Tier;
+(function (Tier) {
+    /** Non-evictable: pins and current summary */
+    Tier[Tier["PINNED"] = 0] = "PINNED";
+    /** Evictable: provider candidates */
+    Tier[Tier["CANDIDATE"] = 1] = "CANDIDATE";
+})(Tier || (Tier = {}));
+/**
+ * Assign tiers to retrieval results
+ *
+ * Tier 0 (non-evictable):
+ * - Active pins
+ * - Current session summary
+ *
+ * Tier 1 (evictable):
+ * - Provider candidates
+ *
+ * @param pins - Pin results
+ * @param currentSummary - Current session summary
+ * @param candidates - Provider candidates
+ * @returns Tiered results in priority order
+ */
+export function assignTiers(pins, currentSummary, candidates) {
+    const tiered = [];
+    // Tier 0: Pins (non-evictable)
+    for (const pin of pins) {
+        tiered.push({
+            tier: Tier.PINNED,
+            content: pin.target.content,
+            id: pin.target.id,
+        });
+    }
+    // Tier 0: Current summary (non-evictable)
+    if (currentSummary) {
+        tiered.push({
+            tier: Tier.PINNED,
+            content: currentSummary.content,
+            id: currentSummary.id,
+        });
+    }
+    // Tier 1: Candidates (evictable, ordered by score)
+    for (const candidate of candidates) {
+        tiered.push({
+            tier: Tier.CANDIDATE,
+            content: candidate.entity.content,
+            id: candidate.entity.id,
+        });
+    }
+    return tiered;
+}
+/**
+ * Filter tiered results by token budget
+ *
+ * Ensures tier 0 (non-evictable) items are always included.
+ * Tier 1 items are included until budget exhausted.
+ *
+ * @param tiered - Tiered results
+ * @param tokenBudget - Maximum tokens to include
+ * @param estimateTokens - Function to estimate tokens for content
+ * @returns Filtered results that fit within budget
+ */
+export function filterByTokenBudget(tiered, tokenBudget, estimateTokens = estimateTokensSimple) {
+    const included = [];
+    let tokensUsed = 0;
+    for (const result of tiered) {
+        const tokens = estimateTokens(result.content);
+        // Always include tier 0 (pins and current summary)
+        if (result.tier === Tier.PINNED) {
+            included.push(result);
+            tokensUsed += tokens;
+            continue;
+        }
+        // Include tier 1 only if within budget
+        if (tokensUsed + tokens <= tokenBudget) {
+            included.push(result);
+            tokensUsed += tokens;
+        }
+    }
+    return included;
+}
+/**
+ * Simple token estimation (characters / 4)
+ *
+ * Rough approximation: ~4 characters per token on average
+ *
+ * @param content - Content to estimate
+ * @returns Estimated token count
+ */
+export function estimateTokensSimple(content) {
+    return Math.ceil(content.length / 4);
+}
+/**
+ * Check if tier 0 results exceed token budget
+ *
+ * Returns true if non-evictable items (pins + current summary) exceed budget.
+ * This is a warning condition - tier 0 items are always included.
+ *
+ * @param tiered - Tiered results
+ * @param tokenBudget - Token budget
+ * @param estimateTokens - Token estimation function
+ * @returns True if tier 0 exceeds budget
+ */
+export function tier0ExceedsBudget(tiered, tokenBudget, estimateTokens = estimateTokensSimple) {
+    let tier0Tokens = 0;
+    for (const result of tiered) {
+        if (result.tier === Tier.PINNED) {
+            tier0Tokens += estimateTokens(result.content);
+        }
+    }
+    return tier0Tokens > tokenBudget;
+}
+//# sourceMappingURL=tiering.js.map

package/dist/retrieval/tiering.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tiering.js","sourceRoot":"","sources":["../../src/retrieval/tiering.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH;;GAEG;AACH,MAAM,CAAN,IAAY,IAKX;AALD,WAAY,IAAI;IACd,8CAA8C;IAC9C,mCAAU,CAAA;IACV,qCAAqC;IACrC,yCAAa,CAAA;AACf,CAAC,EALW,IAAI,KAAJ,IAAI,QAKf;AAWD;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,WAAW,CACzB,IAAiB,EACjB,cAAmC,EACnC,UAA6B;IAE7B,MAAM,MAAM,GAAmB,EAAE,CAAC;IAElC,+BAA+B;IAC/B,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,CAAC,IAAI,CAAC;YACV,IAAI,EAAE,IAAI,CAAC,MAAM;YACjB,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,OAAO;YAC3B,EAAE,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE;SAClB,CAAC,CAAC;IACL,CAAC;IAED,0CAA0C;IAC1C,IAAI,cAAc,EAAE,CAAC;QACnB,MAAM,CAAC,IAAI,CAAC;YACV,IAAI,EAAE,IAAI,CAAC,MAAM;YACjB,OAAO,EAAE,cAAc,CAAC,OAAO;YAC/B,EAAE,EAAE,cAAc,CAAC,EAAE;SACtB,CAAC,CAAC;IACL,CAAC;IAED,mDAAmD;IACnD,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,MAAM,CAAC,IAAI,CAAC;YACV,IAAI,EAAE,IAAI,CAAC,SAAS;YACpB,OAAO,EAAE,SAAS,CAAC,MAAM,CAAC,OAAO;YACjC,EAAE,EAAE,SAAS,CAAC,MAAM,CAAC,EAAE;SACxB,CAAC,CAAC;IACL,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,mBAAmB,CACjC,MAAsB,EACtB,WAAmB,EACnB,iBAA8C,oBAAoB;IAElE,MAAM,QAAQ,GAAmB,EAAE,CAAC;IACpC,IAAI,UAAU,GAAG,CAAC,CAAC;IAEnB,KAAK,MAAM,MAAM,IAAI,MAAM,EAAE,CAAC;QAC5B,MAAM,MAAM,GAAG,cAAc,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAE9C,mDAAmD;QACnD,IAAI,MAAM,CAAC,IAAI,KAAK,IAAI,CAAC,MAAM,EAAE,CAAC;YAChC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACtB,UAAU,IAAI,MAAM,CAAC;YACrB,SAAS;QACX,CAAC;QAED,uCAAuC;QACvC,IAAI,UAAU,GAAG,MAAM,IAAI,WAAW,EAAE,CAAC;YACvC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACtB,UAAU,IAAI,MAAM,CAAC;QACvB,CAAC;IACH,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAe;IAClD,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACvC,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,kBAAkB,CAChC,MAAsB,EACtB,WAAmB,EACnB,iBAA8C,oBAAoB;IAElE,IAAI,WAAW,GAAG,CAAC,CAAC;IAEpB,KAAK,MAAM,MAAM,IAAI,MAAM,EAAE,CAAC;QAC5B,IAAI,MAAM,CAAC,IAAI,KAAK,IAAI,CAAC,MAAM,EAAE,CAAC;YAChC,WAAW,IAAI,cAAc,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAChD,CAAC;IACH,CAAC;IAED,OAAO,WAAW,GAAG,WAAW,CAAC;AACnC,CAAC"}

package/dist/service/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Service orchestration layer
+ */
+export { KindlingService } from './kindling-service.js';
+export type { KindlingStore, KindlingServiceConfig, AppendObservationOptions, CreatePinOptions, CloseCapsuleOptions, } from './kindling-service.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/service/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/service/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,YAAY,EACV,aAAa,EACb,qBAAqB,EACrB,wBAAwB,EACxB,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,uBAAuB,CAAC"}

package/dist/service/index.js

@@ -0,0 +1,5 @@
+/**
+ * Service orchestration layer
+ */
+export { KindlingService } from './kindling-service.js';
+//# sourceMappingURL=index.js.map

package/dist/service/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/service/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC"}