@eddacraft/kindling-core 0.1.0

package/dist/service/kindling-service.d.ts

@@ -0,0 +1,219 @@
+/**
+ * KindlingService - Main orchestration service
+ *
+ * Provides a unified API that combines:
+ * - Capsule lifecycle management
+ * - Observation ingestion
+ * - Retrieval orchestration
+ * - Pin management
+ * - Export/import coordination
+ */
+import type { ID, ScopeIds } from '../types/common.js';
+import type { Observation } from '../types/observation.js';
+import type { Capsule } from '../types/capsule.js';
+import type { Summary } from '../types/summary.js';
+import type { Pin } from '../types/pin.js';
+import type { RetrieveOptions, RetrieveResult, RetrievalProvider } from '../types/retrieval.js';
+import type { OpenCapsuleOptions } from '../capsule/types.js';
+import type { RetrievalStore } from '../retrieval/orchestrator.js';
+import type { ExportStore } from '../export/bundle.js';
+import type { ImportStore } from '../export/restore.js';
+import { type ExportBundle, type ExportBundleOptions, type ExportStats } from '../export/bundle.js';
+import { type ImportOptions, type ImportResult } from '../export/restore.js';
+/**
+ * Store interface required by KindlingService
+ */
+export interface KindlingStore extends RetrievalStore, ExportStore, ImportStore {
+    insertObservation(observation: Observation): void;
+    createCapsule(capsule: Capsule): void;
+    closeCapsule(capsuleId: ID, closedAt?: number): void;
+    attachObservationToCapsule(capsuleId: ID, observationId: ID): void;
+    createSummary(summary: Summary): void;
+    createPin(pin: Pin): void;
+    removePin(pinId: ID): void;
+    redactObservation(observationId: ID): void;
+    getCapsule(capsuleId: ID): Capsule | undefined;
+    getOpenCapsuleForSession(sessionId: string): Capsule | undefined;
+    getObservationById(observationId: ID): Observation | undefined;
+    getSummaryById(summaryId: ID): Summary | undefined;
+    getLatestSummaryForCapsule(capsuleId: ID): Summary | undefined;
+    listActivePins(scopeIds?: Partial<Record<string, string>>, now?: number): Pin[];
+}
+/**
+ * Options for appendObservation
+ */
+export interface AppendObservationOptions {
+    capsuleId?: ID;
+    validate?: boolean;
+}
+/**
+ * Options for creating a pin
+ */
+export interface CreatePinOptions {
+    targetType: 'observation' | 'summary';
+    targetId: ID;
+    note?: string;
+    ttlMs?: number;
+    scopeIds?: Partial<ScopeIds>;
+}
+/**
+ * Options for closing a capsule
+ */
+export interface CloseCapsuleOptions {
+    generateSummary?: boolean;
+    summaryContent?: string;
+    confidence?: number;
+}
+/**
+ * KindlingService configuration
+ */
+export interface KindlingServiceConfig {
+    store: KindlingStore;
+    provider: RetrievalProvider;
+}
+/**
+ * Main Kindling service
+ *
+ * Provides a unified API for all Kindling operations.
+ */
+export declare class KindlingService {
+    private store;
+    private provider;
+    private capsuleManager;
+    constructor(config: KindlingServiceConfig);
+    /**
+     * Open a new capsule
+     *
+     * @param options - Capsule creation options
+     * @returns The created capsule
+     */
+    openCapsule(options: OpenCapsuleOptions): Capsule;
+    /**
+     * Close a capsule
+     *
+     * @param capsuleId - ID of capsule to close
+     * @param options - Closure options
+     * @returns The closed capsule
+     */
+    closeCapsule(capsuleId: ID, options?: CloseCapsuleOptions): Capsule;
+    /**
+     * Append an observation
+     *
+     * @param observation - Observation to append
+     * @param options - Append options
+     */
+    appendObservation(observation: Observation, options?: AppendObservationOptions): void;
+    /**
+     * Retrieve relevant context
+     *
+     * @param options - Retrieval options
+     * @returns Retrieval result with pins, summary, and candidates
+     */
+    retrieve(options: RetrieveOptions): Promise<RetrieveResult>;
+    /**
+     * Create a pin
+     *
+     * @param options - Pin creation options
+     * @returns The created pin
+     */
+    pin(options: CreatePinOptions): Pin;
+    /**
+     * Remove a pin
+     *
+     * @param pinId - ID of pin to remove
+     */
+    unpin(pinId: ID): void;
+    /**
+     * Redact an observation
+     *
+     * Removes content but preserves structure for provenance.
+     *
+     * @param observationId - ID of observation to redact
+     */
+    forget(observationId: ID): void;
+    /**
+     * Get a capsule by ID
+     *
+     * @param capsuleId - Capsule ID
+     * @returns Capsule or undefined if not found
+     */
+    getCapsule(capsuleId: ID): Capsule | undefined;
+    /**
+     * Get open capsule for a session
+     *
+     * @param sessionId - Session ID
+     * @returns Open capsule or undefined
+     */
+    getOpenCapsule(sessionId: string): Capsule | undefined;
+    /**
+     * Get observation by ID
+     *
+     * @param observationId - Observation ID
+     * @returns Observation or undefined if not found
+     */
+    getObservation(observationId: ID): Observation | undefined;
+    /**
+     * Get summary by ID
+     *
+     * @param summaryId - Summary ID
+     * @returns Summary or undefined if not found
+     */
+    getSummary(summaryId: ID): Summary | undefined;
+    /**
+     * List active pins for a scope
+     *
+     * @param scopeIds - Scope to filter by
+     * @returns Array of active pins
+     */
+    listPins(scopeIds?: Partial<ScopeIds>): Pin[];
+    /**
+     * Export database to a portable bundle
+     *
+     * @param options - Export options
+     * @returns Export bundle with dataset and metadata
+     */
+    export(options?: ExportBundleOptions): ExportBundle;
+    /**
+     * Export database to JSON string
+     *
+     * @param options - Export options
+     * @param pretty - Use pretty formatting (default: false)
+     * @returns JSON string
+     */
+    exportToJson(options?: ExportBundleOptions, pretty?: boolean): string;
+    /**
+     * Import from export bundle
+     *
+     * @param bundle - Export bundle to import
+     * @param options - Import options
+     * @returns Import result with counts and errors
+     */
+    import(bundle: ExportBundle, options?: ImportOptions): ImportResult;
+    /**
+     * Import from JSON string
+     *
+     * @param json - JSON string containing export bundle
+     * @param options - Import options
+     * @returns Import result with counts and errors
+     */
+    importFromJson(json: string, options?: ImportOptions): ImportResult;
+    /**
+     * Get statistics for an export bundle
+     *
+     * @param bundle - Export bundle
+     * @returns Statistics about bundle contents
+     */
+    getBundleStats(bundle: ExportBundle): ExportStats;
+    /**
+     * Merge multiple export bundles
+     *
+     * @param bundles - Bundles to merge
+     * @param metadata - Optional metadata for merged bundle
+     * @returns Merged bundle
+     */
+    mergeBundles(bundles: ExportBundle[], metadata?: {
+        description?: string;
+        tags?: string[];
+    }): ExportBundle;
+}
+//# sourceMappingURL=kindling-service.d.ts.map

package/dist/service/kindling-service.d.ts.map

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

package/dist/service/kindling-service.js

@@ -0,0 +1,260 @@
+/**
+ * KindlingService - Main orchestration service
+ *
+ * Provides a unified API that combines:
+ * - Capsule lifecycle management
+ * - Observation ingestion
+ * - Retrieval orchestration
+ * - Pin management
+ * - Export/import coordination
+ */
+import { CapsuleManager } from '../capsule/manager.js';
+import { retrieve as retrieveOrchestrator } from '../retrieval/orchestrator.js';
+import { validateObservation } from '../validation/observation.js';
+import { validatePin } from '../validation/pin.js';
+import { validateSummary } from '../validation/summary.js';
+import { createExportBundle, getBundleStats, serializeBundle, deserializeBundle, } from '../export/bundle.js';
+import { restoreFromBundle, mergeBundles, } from '../export/restore.js';
+/**
+ * Main Kindling service
+ *
+ * Provides a unified API for all Kindling operations.
+ */
+export class KindlingService {
+    store;
+    provider;
+    capsuleManager;
+    constructor(config) {
+        this.store = config.store;
+        this.provider = config.provider;
+        this.capsuleManager = new CapsuleManager({
+            createCapsule: (capsule) => this.store.createCapsule(capsule),
+            closeCapsule: (capsuleId, closedAt) => this.store.closeCapsule(capsuleId, closedAt),
+            getCapsuleById: (capsuleId) => this.store.getCapsule(capsuleId),
+            getOpenCapsuleForSession: (sessionId) => this.store.getOpenCapsuleForSession(sessionId),
+            insertSummary: (summary) => this.store.createSummary(summary),
+        });
+    }
+    /**
+     * Open a new capsule
+     *
+     * @param options - Capsule creation options
+     * @returns The created capsule
+     */
+    openCapsule(options) {
+        return this.capsuleManager.open(options);
+    }
+    /**
+     * Close a capsule
+     *
+     * @param capsuleId - ID of capsule to close
+     * @param options - Closure options
+     * @returns The closed capsule
+     */
+    closeCapsule(capsuleId, options) {
+        const signals = {};
+        // Generate summary if requested
+        if (options?.generateSummary && options.summaryContent) {
+            const summary = {
+                id: `sum_${crypto.randomUUID()}`,
+                capsuleId,
+                content: options.summaryContent,
+                confidence: options.confidence ?? 1.0,
+                createdAt: Date.now(),
+                evidenceRefs: [],
+            };
+            // Validate and store summary
+            const validation = validateSummary(summary);
+            if (!validation.ok) {
+                const errorMessages = validation.error.map(e => e.message).join(', ');
+                throw new Error(`Invalid summary: ${errorMessages}`);
+            }
+            this.store.createSummary(validation.value);
+        }
+        return this.capsuleManager.close(capsuleId, signals);
+    }
+    /**
+     * Append an observation
+     *
+     * @param observation - Observation to append
+     * @param options - Append options
+     */
+    appendObservation(observation, options) {
+        // Validate observation if requested (default: true)
+        let obsToStore = observation;
+        if (options?.validate !== false) {
+            const validation = validateObservation(observation);
+            if (!validation.ok) {
+                const errorMessages = validation.error.map(e => e.message).join(', ');
+                throw new Error(`Invalid observation: ${errorMessages}`);
+            }
+            obsToStore = validation.value;
+        }
+        // Store observation
+        this.store.insertObservation(obsToStore);
+        // Attach to capsule if specified
+        if (options?.capsuleId) {
+            this.store.attachObservationToCapsule(options.capsuleId, obsToStore.id);
+            // Update the capsule manager's cache
+            this.capsuleManager.notifyObservationAttached(options.capsuleId, obsToStore.id);
+        }
+    }
+    /**
+     * Retrieve relevant context
+     *
+     * @param options - Retrieval options
+     * @returns Retrieval result with pins, summary, and candidates
+     */
+    async retrieve(options) {
+        return retrieveOrchestrator(this.store, this.provider, options);
+    }
+    /**
+     * Create a pin
+     *
+     * @param options - Pin creation options
+     * @returns The created pin
+     */
+    pin(options) {
+        const pin = {
+            id: `pin_${crypto.randomUUID()}`,
+            targetType: options.targetType,
+            targetId: options.targetId,
+            reason: options.note,
+            createdAt: Date.now(),
+            expiresAt: options.ttlMs ? Date.now() + options.ttlMs : undefined,
+            scopeIds: options.scopeIds ?? {},
+        };
+        // Validate pin
+        const validation = validatePin(pin);
+        if (!validation.ok) {
+            const errorMessages = validation.error.map(e => e.message).join(', ');
+            throw new Error(`Invalid pin: ${errorMessages}`);
+        }
+        this.store.createPin(validation.value);
+        return validation.value;
+    }
+    /**
+     * Remove a pin
+     *
+     * @param pinId - ID of pin to remove
+     */
+    unpin(pinId) {
+        this.store.removePin(pinId);
+    }
+    /**
+     * Redact an observation
+     *
+     * Removes content but preserves structure for provenance.
+     *
+     * @param observationId - ID of observation to redact
+     */
+    forget(observationId) {
+        this.store.redactObservation(observationId);
+    }
+    /**
+     * Get a capsule by ID
+     *
+     * @param capsuleId - Capsule ID
+     * @returns Capsule or undefined if not found
+     */
+    getCapsule(capsuleId) {
+        return this.capsuleManager.get(capsuleId);
+    }
+    /**
+     * Get open capsule for a session
+     *
+     * @param sessionId - Session ID
+     * @returns Open capsule or undefined
+     */
+    getOpenCapsule(sessionId) {
+        return this.capsuleManager.getOpen({ sessionId });
+    }
+    /**
+     * Get observation by ID
+     *
+     * @param observationId - Observation ID
+     * @returns Observation or undefined if not found
+     */
+    getObservation(observationId) {
+        return this.store.getObservationById(observationId);
+    }
+    /**
+     * Get summary by ID
+     *
+     * @param summaryId - Summary ID
+     * @returns Summary or undefined if not found
+     */
+    getSummary(summaryId) {
+        return this.store.getSummaryById(summaryId);
+    }
+    /**
+     * List active pins for a scope
+     *
+     * @param scopeIds - Scope to filter by
+     * @returns Array of active pins
+     */
+    listPins(scopeIds) {
+        return this.store.listActivePins(scopeIds, Date.now());
+    }
+    /**
+     * Export database to a portable bundle
+     *
+     * @param options - Export options
+     * @returns Export bundle with dataset and metadata
+     */
+    export(options) {
+        return createExportBundle(this.store, options);
+    }
+    /**
+     * Export database to JSON string
+     *
+     * @param options - Export options
+     * @param pretty - Use pretty formatting (default: false)
+     * @returns JSON string
+     */
+    exportToJson(options, pretty = false) {
+        const bundle = this.export(options);
+        return serializeBundle(bundle, pretty);
+    }
+    /**
+     * Import from export bundle
+     *
+     * @param bundle - Export bundle to import
+     * @param options - Import options
+     * @returns Import result with counts and errors
+     */
+    import(bundle, options) {
+        return restoreFromBundle(this.store, bundle, options);
+    }
+    /**
+     * Import from JSON string
+     *
+     * @param json - JSON string containing export bundle
+     * @param options - Import options
+     * @returns Import result with counts and errors
+     */
+    importFromJson(json, options) {
+        const bundle = deserializeBundle(json);
+        return this.import(bundle, options);
+    }
+    /**
+     * Get statistics for an export bundle
+     *
+     * @param bundle - Export bundle
+     * @returns Statistics about bundle contents
+     */
+    getBundleStats(bundle) {
+        return getBundleStats(bundle);
+    }
+    /**
+     * Merge multiple export bundles
+     *
+     * @param bundles - Bundles to merge
+     * @param metadata - Optional metadata for merged bundle
+     * @returns Merged bundle
+     */
+    mergeBundles(bundles, metadata) {
+        return mergeBundles(bundles, metadata);
+    }
+}
+//# sourceMappingURL=kindling-service.js.map

package/dist/service/kindling-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kindling-service.js","sourceRoot":"","sources":["../../src/service/kindling-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AASH,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,QAAQ,IAAI,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AAEhF,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAG3D,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,eAAe,EACf,iBAAiB,GAIlB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,iBAAiB,EACjB,YAAY,GAGb,MAAM,sBAAsB,CAAC;AA6D9B;;;;GAIG;AACH,MAAM,OAAO,eAAe;IAClB,KAAK,CAAgB;IACrB,QAAQ,CAAoB;IAC5B,cAAc,CAAiB;IAEvC,YAAY,MAA6B;QACvC,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;QAC1B,IAAI,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;QAChC,IAAI,CAAC,cAAc,GAAG,IAAI,cAAc,CAAC;YACvC,aAAa,EAAE,CAAC,OAAgB,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,OAAO,CAAC;YACtE,YAAY,EAAE,CAAC,SAAa,EAAE,QAAgB,EAAE,EAAE,CAChD,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,SAAS,EAAE,QAAQ,CAAC;YAC9C,cAAc,EAAE,CAAC,SAAa,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,SAAS,CAAC;YACnE,wBAAwB,EAAE,CAAC,SAAiB,EAAE,EAAE,CAC9C,IAAI,CAAC,KAAK,CAAC,wBAAwB,CAAC,SAAS,CAAC;YAChD,aAAa,EAAE,CAAC,OAAgB,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,OAAO,CAAC;SACvE,CAAC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,WAAW,CAAC,OAA2B;QACrC,OAAO,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC3C,CAAC;IAED;;;;;;OAMG;IACH,YAAY,CAAC,SAAa,EAAE,OAA6B;QACvD,MAAM,OAAO,GAAwB,EAAE,CAAC;QAExC,gCAAgC;QAChC,IAAI,OAAO,EAAE,eAAe,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;YACvD,MAAM,OAAO,GAAY;gBACvB,EAAE,EAAE,OAAO,MAAM,CAAC,UAAU,EAAE,EAAE;gBAChC,SAAS;gBACT,OAAO,EAAE,OAAO,CAAC,cAAc;gBAC/B,UAAU,EAAE,OAAO,CAAC,UAAU,IAAI,GAAG;gBACrC,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;gBACrB,YAAY,EAAE,EAAE;aACjB,CAAC;YAEF,6BAA6B;YAC7B,MAAM,UAAU,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;YAC5C,IAAI,CAAC,UAAU,CAAC,EAAE,EAAE,CAAC;gBACnB,MAAM,aAAa,GAAG,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBACtE,MAAM,IAAI,KAAK,CAAC,oBAAoB,aAAa,EAAE,CAAC,CAAC;YACvD,CAAC;YAED,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;QAC7C,CAAC;QAED,OAAO,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IACvD,CAAC;IAED;;;;;OAKG;IACH,iBAAiB,CAAC,WAAwB,EAAE,OAAkC;QAC5E,oDAAoD;QACpD,IAAI,UAAU,GAAG,WAAW,CAAC;QAC7B,IAAI,OAAO,EAAE,QAAQ,KAAK,KAAK,EAAE,CAAC;YAChC,MAAM,UAAU,GAAG,mBAAmB,CAAC,WAAW,CAAC,CAAC;YACpD,IAAI,CAAC,UAAU,CAAC,EAAE,EAAE,CAAC;gBACnB,MAAM,aAAa,GAAG,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBACtE,MAAM,IAAI,KAAK,CAAC,wBAAwB,aAAa,EAAE,CAAC,CAAC;YAC3D,CAAC;YACD,UAAU,GAAG,UAAU,CAAC,KAAK,CAAC;QAChC,CAAC;QAED,oBAAoB;QACpB,IAAI,CAAC,KAAK,CAAC,iBAAiB,CAAC,UAAU,CAAC,CAAC;QAEzC,iCAAiC;QACjC,IAAI,OAAO,EAAE,SAAS,EAAE,CAAC;YACvB,IAAI,CAAC,KAAK,CAAC,0BAA0B,CAAC,OAAO,CAAC,SAAS,EAAE,UAAU,CAAC,EAAE,CAAC,CAAC;YACxE,qCAAqC;YACrC,IAAI,CAAC,cAAc,CAAC,yBAAyB,CAAC,OAAO,CAAC,SAAS,EAAE,UAAU,CAAC,EAAE,CAAC,CAAC;QAClF,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,QAAQ,CAAC,OAAwB;QACrC,OAAO,oBAAoB,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAClE,CAAC;IAED;;;;;OAKG;IACH,GAAG,CAAC,OAAyB;QAC3B,MAAM,GAAG,GAAQ;YACf,EAAE,EAAE,OAAO,MAAM,CAAC,UAAU,EAAE,EAAE;YAChC,UAAU,EAAE,OAAO,CAAC,UAAU;YAC9B,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,MAAM,EAAE,OAAO,CAAC,IAAI;YACpB,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;YACrB,SAAS,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS;YACjE,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,EAAE;SACjC,CAAC;QAEF,eAAe;QACf,MAAM,UAAU,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;QACpC,IAAI,CAAC,UAAU,CAAC,EAAE,EAAE,CAAC;YACnB,MAAM,aAAa,GAAG,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACtE,MAAM,IAAI,KAAK,CAAC,gBAAgB,aAAa,EAAE,CAAC,CAAC;QACnD,CAAC;QAED,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;QACvC,OAAO,UAAU,CAAC,KAAK,CAAC;IAC1B,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,KAAS;QACb,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC9B,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,aAAiB;QACtB,IAAI,CAAC,KAAK,CAAC,iBAAiB,CAAC,aAAa,CAAC,CAAC;IAC9C,CAAC;IAED;;;;;OAKG;IACH,UAAU,CAAC,SAAa;QACtB,OAAO,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IAC5C,CAAC;IAED;;;;;OAKG;IACH,cAAc,CAAC,SAAiB;QAC9B,OAAO,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC;IACpD,CAAC;IAED;;;;;OAKG;IACH,cAAc,CAAC,aAAiB;QAC9B,OAAO,IAAI,CAAC,KAAK,CAAC,kBAAkB,CAAC,aAAa,CAAC,CAAC;IACtD,CAAC;IAED;;;;;OAKG;IACH,UAAU,CAAC,SAAa;QACtB,OAAO,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC;IAC9C,CAAC;IAED;;;;;OAKG;IACH,QAAQ,CAAC,QAA4B;QACnC,OAAO,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,QAA2C,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;IAC5F,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,OAA6B;QAClC,OAAO,kBAAkB,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IACjD,CAAC;IAED;;;;;;OAMG;IACH,YAAY,CAAC,OAA6B,EAAE,MAAM,GAAG,KAAK;QACxD,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACpC,OAAO,eAAe,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,MAAoB,EAAE,OAAuB;QAClD,OAAO,iBAAiB,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IACxD,CAAC;IAED;;;;;;OAMG;IACH,cAAc,CAAC,IAAY,EAAE,OAAuB;QAClD,MAAM,MAAM,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC;QACvC,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,CAAC;IAED;;;;;OAKG;IACH,cAAc,CAAC,MAAoB;QACjC,OAAO,cAAc,CAAC,MAAM,CAAC,CAAC;IAChC,CAAC;IAED;;;;;;OAMG;IACH,YAAY,CACV,OAAuB,EACvB,QAAoD;QAEpD,OAAO,YAAY,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IACzC,CAAC;CACF"}

package/dist/types/capsule.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Capsule types and definitions
+ *
+ * A Capsule is a bounded unit of meaning that groups related observations
+ * (e.g., a session, a workflow node)
+ */
+import type { ID, Timestamp, ScopeIds } from './common.js';
+/**
+ * Types of capsules
+ */
+export type CapsuleType = 'session' | 'pocketflow_node';
+/**
+ * Capsule lifecycle status
+ */
+export type CapsuleStatus = 'open' | 'closed';
+/**
+ * Capsule entity
+ *
+ * Immutable except for:
+ * - status (transitions from 'open' to 'closed')
+ * - closedAt (set when status changes to 'closed')
+ */
+export interface Capsule {
+    /** Unique identifier (UUIDv4) */
+    id: ID;
+    /** Type of capsule */
+    type: CapsuleType;
+    /**
+     * Human-readable description of capsule purpose
+     * e.g., "Fix authentication bug"
+     */
+    intent: string;
+    /** Lifecycle state */
+    status: CapsuleStatus;
+    /** Timestamp when capsule was opened (epoch milliseconds) */
+    openedAt: Timestamp;
+    /** Timestamp when capsule was closed (epoch milliseconds, undefined if open) */
+    closedAt?: Timestamp;
+    /** Isolation dimensions for scoped queries */
+    scopeIds: ScopeIds;
+    /**
+     * Ordered list of observation IDs attached to this capsule
+     * Order is deterministic (insertion order)
+     */
+    observationIds: ID[];
+    /** Optional reference to summary for this capsule */
+    summaryId?: ID;
+}
+/**
+ * Input for creating a new capsule
+ * Makes id, openedAt, status, observationIds, and summaryId optional
+ */
+export interface CapsuleInput {
+    id?: ID;
+    type: CapsuleType;
+    intent: string;
+    status?: CapsuleStatus;
+    openedAt?: Timestamp;
+    closedAt?: Timestamp;
+    scopeIds: ScopeIds;
+    observationIds?: ID[];
+    summaryId?: ID;
+}
+/**
+ * All valid capsule types
+ */
+export declare const CAPSULE_TYPES: readonly CapsuleType[];
+/**
+ * All valid capsule statuses
+ */
+export declare const CAPSULE_STATUSES: readonly CapsuleStatus[];
+/**
+ * Type guard to check if a string is a valid CapsuleType
+ */
+export declare function isCapsuleType(value: unknown): value is CapsuleType;
+/**
+ * Type guard to check if a string is a valid CapsuleStatus
+ */
+export declare function isCapsuleStatus(value: unknown): value is CapsuleStatus;
+//# sourceMappingURL=capsule.d.ts.map

package/dist/types/capsule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capsule.d.ts","sourceRoot":"","sources":["../../src/types/capsule.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,EAAE,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE3D;;GAEG;AACH,MAAM,MAAM,WAAW,GACnB,SAAS,GACT,iBAAiB,CAAC;AAEtB;;GAEG;AACH,MAAM,MAAM,aAAa,GACrB,MAAM,GACN,QAAQ,CAAC;AAEb;;;;;;GAMG;AACH,MAAM,WAAW,OAAO;IACtB,iCAAiC;IACjC,EAAE,EAAE,EAAE,CAAC;IAEP,sBAAsB;IACtB,IAAI,EAAE,WAAW,CAAC;IAElB;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf,sBAAsB;IACtB,MAAM,EAAE,aAAa,CAAC;IAEtB,6DAA6D;IAC7D,QAAQ,EAAE,SAAS,CAAC;IAEpB,gFAAgF;IAChF,QAAQ,CAAC,EAAE,SAAS,CAAC;IAErB,8CAA8C;IAC9C,QAAQ,EAAE,QAAQ,CAAC;IAEnB;;;OAGG;IACH,cAAc,EAAE,EAAE,EAAE,CAAC;IAErB,qDAAqD;IACrD,SAAS,CAAC,EAAE,EAAE,CAAC;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,EAAE,CAAC,EAAE,EAAE,CAAC;IACR,IAAI,EAAE,WAAW,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,QAAQ,EAAE,QAAQ,CAAC;IACnB,cAAc,CAAC,EAAE,EAAE,EAAE,CAAC;IACtB,SAAS,CAAC,EAAE,EAAE,CAAC;CAChB;AAED;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,SAAS,WAAW,EAGtC,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAAS,aAAa,EAG3C,CAAC;AAEX;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAElE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAEtE"}

package/dist/types/capsule.js

@@ -0,0 +1,33 @@
+/**
+ * Capsule types and definitions
+ *
+ * A Capsule is a bounded unit of meaning that groups related observations
+ * (e.g., a session, a workflow node)
+ */
+/**
+ * All valid capsule types
+ */
+export const CAPSULE_TYPES = [
+    'session',
+    'pocketflow_node',
+];
+/**
+ * All valid capsule statuses
+ */
+export const CAPSULE_STATUSES = [
+    'open',
+    'closed',
+];
+/**
+ * Type guard to check if a string is a valid CapsuleType
+ */
+export function isCapsuleType(value) {
+    return typeof value === 'string' && CAPSULE_TYPES.includes(value);
+}
+/**
+ * Type guard to check if a string is a valid CapsuleStatus
+ */
+export function isCapsuleStatus(value) {
+    return typeof value === 'string' && CAPSULE_STATUSES.includes(value);
+}
+//# sourceMappingURL=capsule.js.map

package/dist/types/capsule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capsule.js","sourceRoot":"","sources":["../../src/types/capsule.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA4EH;;GAEG;AACH,MAAM,CAAC,MAAM,aAAa,GAA2B;IACnD,SAAS;IACT,iBAAiB;CACT,CAAC;AAEX;;GAEG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAA6B;IACxD,MAAM;IACN,QAAQ;CACA,CAAC;AAEX;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,aAAa,CAAC,QAAQ,CAAC,KAAoB,CAAC,CAAC;AACnF,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,gBAAgB,CAAC,QAAQ,CAAC,KAAsB,CAAC,CAAC;AACxF,CAAC"}

package/dist/types/common.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Common types used across Kindling packages
+ */
+/**
+ * Unique identifier for entities
+ * Implementation uses UUIDv4 format
+ */
+export type ID = string;
+/**
+ * Timestamp in epoch milliseconds
+ */
+export type Timestamp = number;
+/**
+ * Scope identifiers for multi-dimensional isolation
+ *
+ * All fields are optional to support partial scoping:
+ * - sessionId: Isolate by session (e.g., OpenCode session)
+ * - repoId: Isolate by repository path
+ * - agentId: Isolate by agent (future)
+ * - userId: Isolate by user (future)
+ * - taskId: Link to external task system (e.g., Beads task ID)
+ */
+export interface ScopeIds {
+    sessionId?: string;
+    repoId?: string;
+    agentId?: string;
+    userId?: string;
+    taskId?: string;
+}
+/**
+ * Result type for operations that can fail
+ */
+export type Result<T, E = Error> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: E;
+};
+/**
+ * Validation error details
+ */
+export interface ValidationError {
+    field: string;
+    message: string;
+    value?: unknown;
+}
+/**
+ * Helper to create a success result
+ */
+export declare function ok<T>(value: T): Result<T, never>;
+/**
+ * Helper to create an error result
+ */
+export declare function err<E>(error: E): Result<never, E>;
+//# sourceMappingURL=common.d.ts.map

package/dist/types/common.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../src/types/common.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;GAGG;AACH,MAAM,MAAM,EAAE,GAAG,MAAM,CAAC;AAExB;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC;AAE/B;;;;;;;;;GASG;AACH,MAAM,WAAW,QAAQ;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,MAAM,MAAM,CAAC,CAAC,EAAE,CAAC,GAAG,KAAK,IAC3B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GACtB;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,CAAC;AAE5B;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,wBAAgB,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,CAEhD;AAED;;GAEG;AACH,wBAAgB,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAEjD"}