@eddacraft/anvil-kindling-integration 0.1.0

package/src/index.ts

@@ -0,0 +1,254 @@
+/**
+ * Kindling Integration (v1)
+ *
+ * This package provides the complete integration layer between Anvil and Kindling.
+ *
+ * Three surfaces:
+ *
+ * 1. Observation Contract (Write-Only)
+ *    - 11 observation kinds covering session, plan, gate, action, constraint, human, error
+ *    - Immutable, timestamped, linked facts
+ *
+ * 2. Query Contract (Read-Only)
+ *    - 4 query scopes: session, plan, gate, action
+ *    - Mandatory constraints, throttling, output guarantees
+ *
+ * 3. Service Layer (Orchestration)
+ *    - KindlingService: validation, sensitive-data checks, store delegation
+ *    - Emitters: fire-and-forget observation emission
+ *    - KindlingQueryService: high-level query convenience methods
+ *    - Configuration, retention, and query limit enforcement
+ *
+ * GOVERNING RULE:
+ * Kindling is a system of record, not a reasoning engine.
+ * Queries may retrieve facts; interpretation is the caller's responsibility.
+ *
+ * @packageDocumentation
+ */
+
+// =============================================================================
+// Observation Contract (Write-Only)
+// =============================================================================
+
+export {
+  // Version
+  OBSERVATION_CONTRACT_VERSION,
+
+  // Schemas (individual)
+  SessionStartObservationSchema,
+  SessionEndObservationSchema,
+  PlanCreatedObservationSchema,
+  PlanEditedObservationSchema,
+  PlanApprovedObservationSchema,
+  PlanRejectedObservationSchema,
+  ActionExecutedObservationSchema,
+  GateEvaluatedObservationSchema,
+  ConstraintAppliedObservationSchema,
+  HumanInputObservationSchema,
+  ErrorObservationSchema,
+
+  // Schema (union)
+  ObservationSchema,
+
+  // Types
+  type SessionStartObservation,
+  type SessionEndObservation,
+  type PlanCreatedObservation,
+  type PlanEditedObservation,
+  type PlanApprovedObservation,
+  type PlanRejectedObservation,
+  type ActionExecutedObservation,
+  type GateEvaluatedObservation,
+  type ConstraintAppliedObservation,
+  type HumanInputObservation,
+  type ErrorObservation,
+  type Observation,
+
+  // Utilities
+  validateObservation,
+  containsSensitiveData,
+} from './observation-contract.js';
+
+// =============================================================================
+// Query Contract (Read-Only)
+// =============================================================================
+
+export {
+  // Version
+  KINDLING_QUERY_CONTRACT_VERSION,
+
+  // Query scopes
+  QueryScopeSchema,
+  type QueryScope,
+
+  // Result shape
+  ResultShapeSchema,
+  type ResultShape,
+
+  // Output format
+  OutputFormatSchema,
+  type OutputFormat,
+
+  // Query requests (individual)
+  SessionQuerySchema,
+  PlanQuerySchema,
+  GateQuerySchema,
+  ActionQuerySchema,
+
+  // Query request (union)
+  QueryRequestSchema,
+  QueryRequestBaseSchema,
+  type QueryRequest,
+  type QueryRequestBase,
+  type SessionQuery,
+  type PlanQuery,
+  type GateQuery,
+  type ActionQuery,
+
+  // Query response
+  QueryResponseSchema,
+  QueryResponseMetadataSchema,
+  ProvenanceLinkSchema,
+  type QueryResponse,
+  type QueryResponseMetadata,
+  type ProvenanceLink,
+
+  // Utilities
+  validateQueryRequest,
+  validateQueryResponse,
+} from './query-contract.js';
+
+// Re-export Observation from query-contract for convenience
+export { ObservationSchema as QueryObservationSchema } from './query-contract.js';
+
+// =============================================================================
+// Configuration (KINDLING-002)
+// =============================================================================
+
+export {
+  KindlingConfigSchema,
+  CaptureConfigSchema,
+  RetentionConfigSchema,
+  QueryLimitConfigSchema,
+  type KindlingConfig,
+  type CaptureConfig,
+  type RetentionConfig,
+  type QueryLimitConfig,
+  DEFAULT_KINDLING_CONFIG,
+  loadKindlingConfig,
+  shouldCapture,
+} from './config.js';
+
+// =============================================================================
+// Service Layer (KINDLING-001)
+// =============================================================================
+
+export {
+  type IKindlingStore,
+  NoOpKindlingStore,
+  KindlingService,
+  ObservationValidationError,
+  QueryValidationError,
+  createKindlingService,
+} from './kindling-service.js';
+
+// =============================================================================
+// Sensitive Data Validation (KINDLING-015)
+// =============================================================================
+
+export {
+  validateNoSensitiveData,
+  redactSensitiveFields,
+  type SensitiveDataValidationResult,
+} from './sensitive-data-validator.js';
+
+// =============================================================================
+// Emitters (KINDLING-003 through 008)
+// =============================================================================
+
+export {
+  // Session
+  emitSessionStart,
+  emitSessionEnd,
+  type SessionStartContext,
+  type SessionEndOutcome,
+
+  // Gate
+  emitGateEvaluated,
+  type GateResult,
+
+  // Action
+  emitActionExecuted,
+  type ActionDetails,
+
+  // Plan
+  emitPlanCreated,
+  emitPlanEdited,
+  emitPlanApproved,
+  emitPlanRejected,
+  type PlanCreatedInput,
+  type PlanEditedInput,
+  type PlanApprovedInput,
+  type PlanRejectedInput,
+
+  // Human Input
+  emitHumanInput,
+  type HumanInputDetails,
+
+  // Constraint
+  emitConstraintApplied,
+  type ConstraintDetails,
+
+  // Error
+  emitError,
+  type ErrorDetails,
+} from './emitters/index.js';
+
+// =============================================================================
+// Query Service (KINDLING-009)
+// =============================================================================
+
+export {
+  KindlingQueryService,
+  type QueryOptions,
+  type SessionQueryOptions,
+  type PlanQueryOptions,
+  type ActionQueryOptions,
+} from './query-service.js';
+
+// =============================================================================
+// Query Limits (KINDLING-010)
+// =============================================================================
+
+export { enforceQueryLimits, limitsFromConfig, type QueryLimits } from './query-limits.js';
+
+// =============================================================================
+// Retention (KINDLING-016)
+// =============================================================================
+
+export {
+  type IRetentionCapableStore,
+  type StorageStats,
+  type PruneResult,
+  isRetentionCapable,
+  pruneOldObservations,
+  getStorageStats,
+} from './retention.js';
+
+// =============================================================================
+// Status Utility (KINDLING-014)
+// =============================================================================
+
+export {
+  getKindlingStatus,
+  formatKindlingStatus,
+  type KindlingStatus,
+  type KindlingStatusConfig,
+  type KindlingStatusStore,
+} from './status.js';
+
+// =============================================================================
+// Adapter (Anvil → Kindling Bridge)
+// =============================================================================
+
+export { AnvilKindlingAdapter, type AnvilKindlingAdapterConfig } from './adapter.js';

package/src/kindling-service.ts

@@ -0,0 +1,272 @@
+/**
+ * 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 { validateObservation } from './observation-contract.js';
+import type { QueryRequest, QueryResponse } from './query-contract.js';
+import { QueryRequestSchema } from './query-contract.js';
+import type { KindlingConfig } from './config.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');
+
+// =============================================================================
+// Store Interface (Abstract Adapter)
+// =============================================================================
+
+/**
+ * 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 (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 implements IKindlingStore {
+  async emit(_observation: Observation): Promise<void> {
+    // Intentionally empty -- disabled mode
+  }
+
+  async query(_request: QueryRequest): Promise<QueryResponse> {
+    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(): Promise<void> {
+    // Intentionally empty -- nothing to close
+  }
+}
+
+// =============================================================================
+// Service Errors
+// =============================================================================
+
+/**
+ * Error thrown when observation validation fails
+ */
+export class ObservationValidationError extends Error {
+  constructor(
+    message: string,
+    public readonly issues: string[]
+  ) {
+    super(message);
+    this.name = 'ObservationValidationError';
+  }
+}
+
+/**
+ * Error thrown when query validation fails
+ */
+export class QueryValidationError extends Error {
+  constructor(message: string) {
+    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 {
+  private readonly store: IKindlingStore;
+  private readonly config: KindlingConfig;
+  private closed = false;
+
+  constructor(store: IKindlingStore, config: KindlingConfig) {
+    this.store = store;
+    this.config = config;
+    debug('KindlingService created', { enabled: config.enabled });
+  }
+
+  /**
+   * Whether the service is enabled (will actually emit observations)
+   */
+  get enabled(): boolean {
+    return this.config.enabled;
+  }
+
+  /**
+   * The active configuration
+   */
+  get configuration(): Readonly<KindlingConfig> {
+    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: Observation): Promise<void> {
+    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: QueryRequest): Promise<QueryResponse> {
+    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
+      ),
+    } as QueryRequest;
+
+    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(): Promise<void> {
+    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: KindlingConfig = DEFAULT_KINDLING_CONFIG,
+  store?: IKindlingStore
+): KindlingService {
+  const effectiveStore = store ?? new NoOpKindlingStore();
+  debug('creating KindlingService', { enabled: config.enabled, hasStore: !!store });
+  return new KindlingService(effectiveStore, config);
+}