@eddacraft/anvil-kindling-integration 0.1.0

package/dist/kindling-service.d.ts

@@ -0,0 +1,122 @@
+/**
+ * KindlingService (KINDLING-001)
+ *
+ * Core service wrapper that mediates between Anvil and the Kindling store.
+ * Handles validation, sensitive-data checks, and delegation to the store adapter.
+ *
+ * The service is built against the abstract `IKindlingStore` interface so that
+ * it compiles without @kindling/core or @kindling/store-sqlite installed.
+ * The actual storage backend is plugged in at runtime via the factory function.
+ *
+ * When no store is provided, the service operates in "disabled mode" using a
+ * no-op store that silently discards all observations.
+ */
+import type { Observation } from './observation-contract.js';
+import type { QueryRequest, QueryResponse } from './query-contract.js';
+import type { KindlingConfig } from './config.js';
+/**
+ * Abstract storage adapter interface.
+ *
+ * Implementations must provide emit (write), query (read), and close (cleanup).
+ * This decouples the service layer from any concrete Kindling SDK dependency.
+ */
+export interface IKindlingStore {
+    /**
+     * Persist an observation to the store.
+     * The observation has already been validated and redacted by the service layer.
+     */
+    emit(observation: Observation): Promise<void>;
+    /**
+     * Execute a bounded query against the store.
+     * The request has already been validated by the service layer.
+     */
+    query(request: QueryRequest): Promise<QueryResponse>;
+    /**
+     * Release resources (close database connections, flush buffers, etc.)
+     */
+    close(): Promise<void>;
+}
+/**
+ * No-op store used when Kindling is disabled or no store is provided.
+ * All operations succeed silently without side effects.
+ */
+export declare class NoOpKindlingStore implements IKindlingStore {
+    emit(_observation: Observation): Promise<void>;
+    query(_request: QueryRequest): Promise<QueryResponse>;
+    close(): Promise<void>;
+}
+/**
+ * Error thrown when observation validation fails
+ */
+export declare class ObservationValidationError extends Error {
+    readonly issues: string[];
+    constructor(message: string, issues: string[]);
+}
+/**
+ * Error thrown when query validation fails
+ */
+export declare class QueryValidationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Core Kindling service that wraps the store adapter with validation,
+ * sensitive-data checks, and config-driven behavior.
+ */
+export declare class KindlingService {
+    private readonly store;
+    private readonly config;
+    private closed;
+    constructor(store: IKindlingStore, config: KindlingConfig);
+    /**
+     * Whether the service is enabled (will actually emit observations)
+     */
+    get enabled(): boolean;
+    /**
+     * The active configuration
+     */
+    get configuration(): Readonly<KindlingConfig>;
+    /**
+     * Emit an observation to the Kindling store.
+     *
+     * This method is designed to be async and non-blocking. It:
+     * 1. Checks if the service is enabled and the observation kind should be captured
+     * 2. Validates the observation against the contract schema
+     * 3. Checks for and redacts sensitive data
+     * 4. Delegates to the store adapter
+     *
+     * Validation errors are thrown. Store errors are thrown (callers should catch
+     * if they want fire-and-forget semantics -- see emitters).
+     *
+     * @param observation - The observation to emit
+     * @throws ObservationValidationError if the observation is invalid
+     */
+    emit(observation: Observation): Promise<void>;
+    /**
+     * Execute a query against the Kindling store.
+     *
+     * Validates the query request against the contract schema and enforces
+     * configured query limits before delegating to the store.
+     *
+     * @param request - The query request
+     * @returns Query response with observations
+     * @throws QueryValidationError if the request is invalid
+     */
+    query(request: QueryRequest): Promise<QueryResponse>;
+    /**
+     * Close the service and release underlying store resources.
+     * After calling close(), emit() becomes a no-op and query() throws.
+     */
+    close(): Promise<void>;
+}
+/**
+ * Create a KindlingService instance.
+ *
+ * If no store is provided, the service operates in disabled mode with a no-op store.
+ * This allows code to unconditionally call emit/query without checking for null.
+ *
+ * @param config - Kindling configuration (defaults to disabled config)
+ * @param store - Optional store adapter (defaults to NoOpKindlingStore)
+ * @returns Configured KindlingService instance
+ */
+export declare function createKindlingService(config?: KindlingConfig, store?: IKindlingStore): KindlingService;
+//# sourceMappingURL=kindling-service.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"kindling-service.d.ts","sourceRoot":"","sources":["../src/kindling-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAE7D,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEvE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAWlD;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,IAAI,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9C;;;OAGG;IACH,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAErD;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAMD;;;GAGG;AACH,qBAAa,iBAAkB,YAAW,cAAc;IAChD,IAAI,CAAC,YAAY,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAI9C,KAAK,CAAC,QAAQ,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC;IAcrD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B;AAMD;;GAEG;AACH,qBAAa,0BAA2B,SAAQ,KAAK;aAGjC,MAAM,EAAE,MAAM,EAAE;gBADhC,OAAO,EAAE,MAAM,EACC,MAAM,EAAE,MAAM,EAAE;CAKnC;AAED;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,OAAO,EAAE,MAAM;CAI5B;AAMD;;;GAGG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiB;IACvC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;IACxC,OAAO,CAAC,MAAM,CAAS;gBAEX,KAAK,EAAE,cAAc,EAAE,MAAM,EAAE,cAAc;IAMzD;;OAEG;IACH,IAAI,OAAO,IAAI,OAAO,CAErB;IAED;;OAEG;IACH,IAAI,aAAa,IAAI,QAAQ,CAAC,cAAc,CAAC,CAE5C;IAED;;;;;;;;;;;;;;OAcG;IACG,IAAI,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAmCnD;;;;;;;;;OASG;IACG,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC;IA8B1D;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAQ7B;AAMD;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,GAAE,cAAwC,EAChD,KAAK,CAAC,EAAE,cAAc,GACrB,eAAe,CAIjB"}

package/dist/kindling-service.js

@@ -0,0 +1,203 @@
+/**
+ * KindlingService (KINDLING-001)
+ *
+ * Core service wrapper that mediates between Anvil and the Kindling store.
+ * Handles validation, sensitive-data checks, and delegation to the store adapter.
+ *
+ * The service is built against the abstract `IKindlingStore` interface so that
+ * it compiles without @kindling/core or @kindling/store-sqlite installed.
+ * The actual storage backend is plugged in at runtime via the factory function.
+ *
+ * When no store is provided, the service operates in "disabled mode" using a
+ * no-op store that silently discards all observations.
+ */
+import { validateObservation } from './observation-contract.js';
+import { QueryRequestSchema } from './query-contract.js';
+import { DEFAULT_KINDLING_CONFIG, shouldCapture } from './config.js';
+import { validateNoSensitiveData, redactSensitiveFields } from './sensitive-data-validator.js';
+import { createDebugger } from './utils/debug.js';
+const debug = createDebugger('kindling');
+// =============================================================================
+// No-Op Store (Disabled Mode)
+// =============================================================================
+/**
+ * No-op store used when Kindling is disabled or no store is provided.
+ * All operations succeed silently without side effects.
+ */
+export class NoOpKindlingStore {
+    async emit(_observation) {
+        // Intentionally empty -- disabled mode
+    }
+    async query(_request) {
+        return {
+            metadata: {
+                query_id: crypto.randomUUID(),
+                executed_at: new Date().toISOString(),
+                contract_version: '1.0.0',
+                result_count: 0,
+                truncated: false,
+                truncation_reason: 'none',
+            },
+            observations: [],
+        };
+    }
+    async close() {
+        // Intentionally empty -- nothing to close
+    }
+}
+// =============================================================================
+// Service Errors
+// =============================================================================
+/**
+ * Error thrown when observation validation fails
+ */
+export class ObservationValidationError extends Error {
+    issues;
+    constructor(message, issues) {
+        super(message);
+        this.issues = issues;
+        this.name = 'ObservationValidationError';
+    }
+}
+/**
+ * Error thrown when query validation fails
+ */
+export class QueryValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'QueryValidationError';
+    }
+}
+// =============================================================================
+// KindlingService
+// =============================================================================
+/**
+ * Core Kindling service that wraps the store adapter with validation,
+ * sensitive-data checks, and config-driven behavior.
+ */
+export class KindlingService {
+    store;
+    config;
+    closed = false;
+    constructor(store, config) {
+        this.store = store;
+        this.config = config;
+        debug('KindlingService created', { enabled: config.enabled });
+    }
+    /**
+     * Whether the service is enabled (will actually emit observations)
+     */
+    get enabled() {
+        return this.config.enabled;
+    }
+    /**
+     * The active configuration
+     */
+    get configuration() {
+        return this.config;
+    }
+    /**
+     * Emit an observation to the Kindling store.
+     *
+     * This method is designed to be async and non-blocking. It:
+     * 1. Checks if the service is enabled and the observation kind should be captured
+     * 2. Validates the observation against the contract schema
+     * 3. Checks for and redacts sensitive data
+     * 4. Delegates to the store adapter
+     *
+     * Validation errors are thrown. Store errors are thrown (callers should catch
+     * if they want fire-and-forget semantics -- see emitters).
+     *
+     * @param observation - The observation to emit
+     * @throws ObservationValidationError if the observation is invalid
+     */
+    async emit(observation) {
+        if (this.closed) {
+            debug('emit skipped: service is closed');
+            return;
+        }
+        // Check if this kind should be captured
+        if (!shouldCapture(this.config, observation.kind)) {
+            debug('emit skipped: kind not captured', observation.kind);
+            return;
+        }
+        // Validate against the contract schema
+        const validation = validateObservation(observation);
+        if (!validation.success) {
+            debug('emit validation failed', validation.error);
+            throw new ObservationValidationError(`Invalid observation: ${validation.error}`, [
+                validation.error ?? 'Unknown validation error',
+            ]);
+        }
+        // Check for sensitive data and redact if found
+        const sensitiveCheck = validateNoSensitiveData(observation);
+        let safeObservation = observation;
+        if (sensitiveCheck.hasSensitiveData) {
+            debug('sensitive data detected, redacting', sensitiveCheck.issues);
+            safeObservation = redactSensitiveFields(observation);
+        }
+        // Delegate to store (async, non-blocking from caller's perspective)
+        debug('emitting observation', { kind: observation.kind, session_id: observation.session_id });
+        await this.store.emit(safeObservation);
+    }
+    /**
+     * Execute a query against the Kindling store.
+     *
+     * Validates the query request against the contract schema and enforces
+     * configured query limits before delegating to the store.
+     *
+     * @param request - The query request
+     * @returns Query response with observations
+     * @throws QueryValidationError if the request is invalid
+     */
+    async query(request) {
+        if (this.closed) {
+            debug('query rejected: service is closed');
+            throw new QueryValidationError('Service is closed');
+        }
+        // Validate the request
+        const validation = QueryRequestSchema.safeParse(request);
+        if (!validation.success) {
+            debug('query validation failed', validation.error.format());
+            throw new QueryValidationError(`Invalid query request: ${validation.error.format()._errors.join(', ')}`);
+        }
+        debug('executing query', { scope: request.scope });
+        // Enforce configured query limits (use config defaults if request has higher values)
+        const limitedRequest = {
+            ...validation.data,
+            max_results: Math.min(validation.data.max_results, this.config.query_limits.max_results),
+            max_payload_bytes: Math.min(validation.data.max_payload_bytes, this.config.query_limits.max_payload_bytes),
+        };
+        return this.store.query(limitedRequest);
+    }
+    /**
+     * Close the service and release underlying store resources.
+     * After calling close(), emit() becomes a no-op and query() throws.
+     */
+    async close() {
+        if (this.closed) {
+            return;
+        }
+        debug('closing KindlingService');
+        this.closed = true;
+        await this.store.close();
+    }
+}
+// =============================================================================
+// Factory
+// =============================================================================
+/**
+ * Create a KindlingService instance.
+ *
+ * If no store is provided, the service operates in disabled mode with a no-op store.
+ * This allows code to unconditionally call emit/query without checking for null.
+ *
+ * @param config - Kindling configuration (defaults to disabled config)
+ * @param store - Optional store adapter (defaults to NoOpKindlingStore)
+ * @returns Configured KindlingService instance
+ */
+export function createKindlingService(config = DEFAULT_KINDLING_CONFIG, store) {
+    const effectiveStore = store ?? new NoOpKindlingStore();
+    debug('creating KindlingService', { enabled: config.enabled, hasStore: !!store });
+    return new KindlingService(effectiveStore, config);
+}