@eddacraft/anvil-kindling-integration 0.1.0

package/package.json

@@ -0,0 +1,114 @@
+{
+  "name": "@eddacraft/anvil-kindling-integration",
+  "version": "0.1.0",
+  "description": "Kindling memory integration contracts for Anvil v1",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./query": {
+      "types": "./dist/query-contract.d.ts",
+      "import": "./dist/query-contract.js"
+    },
+    "./observation": {
+      "types": "./dist/observation-contract.d.ts",
+      "import": "./dist/observation-contract.js"
+    },
+    "./config": {
+      "types": "./dist/config.d.ts",
+      "import": "./dist/config.js"
+    },
+    "./service": {
+      "types": "./dist/kindling-service.d.ts",
+      "import": "./dist/kindling-service.js"
+    },
+    "./emitters": {
+      "types": "./dist/emitters/index.d.ts",
+      "import": "./dist/emitters/index.js"
+    },
+    "./emitters/session": {
+      "types": "./dist/emitters/session-emitter.d.ts",
+      "import": "./dist/emitters/session-emitter.js"
+    },
+    "./emitters/gate": {
+      "types": "./dist/emitters/gate-emitter.d.ts",
+      "import": "./dist/emitters/gate-emitter.js"
+    },
+    "./emitters/action": {
+      "types": "./dist/emitters/action-emitter.d.ts",
+      "import": "./dist/emitters/action-emitter.js"
+    },
+    "./emitters/plan": {
+      "types": "./dist/emitters/plan-emitter.d.ts",
+      "import": "./dist/emitters/plan-emitter.js"
+    },
+    "./emitters/human-input": {
+      "types": "./dist/emitters/human-input-emitter.d.ts",
+      "import": "./dist/emitters/human-input-emitter.js"
+    },
+    "./emitters/constraint": {
+      "types": "./dist/emitters/constraint-emitter.d.ts",
+      "import": "./dist/emitters/constraint-emitter.js"
+    },
+    "./emitters/error": {
+      "types": "./dist/emitters/error-emitter.d.ts",
+      "import": "./dist/emitters/error-emitter.js"
+    },
+    "./query-service": {
+      "types": "./dist/query-service.d.ts",
+      "import": "./dist/query-service.js"
+    },
+    "./query-limits": {
+      "types": "./dist/query-limits.d.ts",
+      "import": "./dist/query-limits.js"
+    },
+    "./sensitive-data": {
+      "types": "./dist/sensitive-data-validator.d.ts",
+      "import": "./dist/sensitive-data-validator.js"
+    },
+    "./retention": {
+      "types": "./dist/retention.d.ts",
+      "import": "./dist/retention.js"
+    },
+    "./status": {
+      "types": "./dist/status.d.ts",
+      "import": "./dist/status.js"
+    },
+    "./adapter": {
+      "types": "./dist/adapter.d.ts",
+      "import": "./dist/adapter.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@eddacraft/kindling-core": "0.1.1",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.3",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "keywords": [
+    "anvil",
+    "kindling",
+    "memory",
+    "observability",
+    "governance"
+  ],
+  "license": "PROPRIETARY",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest",
+    "bench": "vitest bench",
+    "generate:openapi": "tsx scripts/generate-openapi.ts",
+    "lint": "eslint src --ext .ts"
+  }
+}

package/src/adapter.ts

@@ -0,0 +1,117 @@
+/**
+ * Anvil-Kindling Adapter
+ *
+ * Maps Anvil's 11 observation kinds (rich, domain-specific schemas)
+ * to Kindling core's generic observation model for storage and retrieval.
+ *
+ * Anvil observation data is serialized to `content` as JSON.
+ * The original Anvil kind is preserved in `provenance.anvil_kind`.
+ */
+
+import { randomUUID } from 'node:crypto';
+import type { KindlingService, Capsule, ID } from '@eddacraft/kindling-core';
+import type { Observation as AnvilObservation } from './observation-contract.js';
+import { OBSERVATION_CONTRACT_VERSION } from './observation-contract.js';
+import { createDebugger } from './utils/debug.js';
+
+const debug = createDebugger('kindling');
+
+/** Map Anvil observation kinds to Kindling's generic observation kinds */
+const KIND_MAP: Record<AnvilObservation['kind'], string> = {
+  session_start: 'message',
+  session_end: 'message',
+  plan_created: 'message',
+  plan_edited: 'message',
+  plan_approved: 'message',
+  plan_rejected: 'message',
+  action_executed: 'command',
+  gate_evaluated: 'command',
+  constraint_applied: 'message',
+  human_input: 'message',
+  error: 'error',
+};
+
+export interface AnvilKindlingAdapterConfig {
+  service: KindlingService;
+  /** Repo path for scope isolation */
+  repoId?: string;
+}
+
+/**
+ * Bridges Anvil observation emission to Kindling storage.
+ *
+ * Usage:
+ * ```ts
+ * const adapter = new AnvilKindlingAdapter({ service });
+ * const capsule = adapter.startSession(sessionId, scopeIds);
+ * adapter.emit(observation);
+ * adapter.endSession(capsule.id);
+ * ```
+ */
+export class AnvilKindlingAdapter {
+  private service: KindlingService;
+  private repoId: string | undefined;
+
+  constructor(config: AnvilKindlingAdapterConfig) {
+    this.service = config.service;
+    this.repoId = config.repoId;
+    debug('AnvilKindlingAdapter created', { repoId: config.repoId });
+  }
+
+  /**
+   * Open a Kindling capsule for an Anvil session.
+   * Call this when a CLI command starts.
+   */
+  startSession(sessionId: string, intent: string): Capsule {
+    debug('starting session', { sessionId, intent });
+    return this.service.openCapsule({
+      type: 'session',
+      intent,
+      scopeIds: {
+        sessionId,
+        repoId: this.repoId,
+      },
+    });
+  }
+
+  /**
+   * Close the capsule for a session.
+   * Call this when a CLI command ends.
+   */
+  endSession(capsuleId: ID, summaryContent?: string): Capsule {
+    debug('ending session', { capsuleId });
+    return this.service.closeCapsule(capsuleId, {
+      generateSummary: !!summaryContent,
+      summaryContent,
+    });
+  }
+
+  /**
+   * Emit an Anvil observation to Kindling.
+   * The rich Anvil schema is serialized to content; the original kind
+   * is preserved in provenance for filtering.
+   */
+  emit(observation: AnvilObservation, capsuleId?: ID): void {
+    debug('emitting observation via adapter', { kind: observation.kind, capsuleId });
+    const kindlingObs = {
+      id: randomUUID(),
+      kind: KIND_MAP[observation.kind] as 'message' | 'command' | 'error',
+      content: JSON.stringify(observation),
+      provenance: {
+        anvil_kind: observation.kind,
+        anvil_contract_version: OBSERVATION_CONTRACT_VERSION,
+      },
+      ts: Date.now(),
+      scopeIds: {
+        sessionId: observation.session_id,
+        repoId: this.repoId,
+      },
+      redacted: false,
+    };
+
+    this.service.appendObservation(kindlingObs, {
+      capsuleId,
+      validate: true,
+    });
+  }
+}

package/src/config.ts

@@ -0,0 +1,202 @@
+/**
+ * Kindling Configuration Schema (KINDLING-002)
+ *
+ * Defines configuration for the Kindling integration layer.
+ * Configuration is read from `.anvilrc` or `anvil.config.json` in the project root.
+ *
+ * @see kindling-service.ts for how config is consumed
+ */
+
+import { z } from 'zod';
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+// =============================================================================
+// Configuration Schema
+// =============================================================================
+
+/**
+ * Capture flags: which observation kinds to record
+ */
+export const CaptureConfigSchema = z.object({
+  sessions: z.boolean().default(true).describe('Record session start/end'),
+  gates: z.boolean().default(true).describe('Record gate evaluations'),
+  actions: z.boolean().default(true).describe('Record action executions'),
+  plans: z.boolean().default(true).describe('Record plan lifecycle events'),
+  human_inputs: z.boolean().default(true).describe('Record human inputs'),
+  constraints: z.boolean().default(true).describe('Record constraint applications'),
+  errors: z.boolean().default(true).describe('Record errors'),
+});
+
+export type CaptureConfig = z.infer<typeof CaptureConfigSchema>;
+
+/**
+ * Retention policy
+ */
+export const RetentionConfigSchema = z.object({
+  days: z.number().int().positive().default(90).describe('Days to retain observations'),
+  auto_prune: z.boolean().default(false).describe('Automatically prune on session start'),
+});
+
+export type RetentionConfig = z.infer<typeof RetentionConfigSchema>;
+
+/**
+ * Query limit defaults
+ */
+export const QueryLimitConfigSchema = z.object({
+  max_results: z
+    .number()
+    .int()
+    .positive()
+    .max(1000)
+    .default(100)
+    .describe('Default max results per query'),
+  max_payload_bytes: z
+    .number()
+    .int()
+    .positive()
+    .max(10 * 1024 * 1024)
+    .default(1024 * 1024)
+    .describe('Default max payload size in bytes'),
+});
+
+export type QueryLimitConfig = z.infer<typeof QueryLimitConfigSchema>;
+
+/**
+ * Full Kindling configuration
+ */
+export const KindlingConfigSchema = z.object({
+  enabled: z.boolean().default(false).describe('Whether Kindling recording is active'),
+  database_path: z
+    .string()
+    .default('.anvil/kindling.db')
+    .describe('Path to the SQLite database (relative to project root)'),
+  retention: RetentionConfigSchema.default(() => ({
+    days: 90,
+    auto_prune: false,
+  })),
+  capture: CaptureConfigSchema.default(() => ({
+    sessions: true,
+    gates: true,
+    actions: true,
+    plans: true,
+    human_inputs: true,
+    constraints: true,
+    errors: true,
+  })),
+  query_limits: QueryLimitConfigSchema.default(() => ({
+    max_results: 100,
+    max_payload_bytes: 1024 * 1024,
+  })),
+});
+
+export type KindlingConfig = z.infer<typeof KindlingConfigSchema>;
+
+// =============================================================================
+// Default Configuration
+// =============================================================================
+
+/**
+ * Default configuration: disabled, sensible defaults for everything else
+ */
+export const DEFAULT_KINDLING_CONFIG: KindlingConfig = KindlingConfigSchema.parse({});
+
+// =============================================================================
+// Configuration Loading
+// =============================================================================
+
+/**
+ * Known configuration file names, checked in order
+ */
+const CONFIG_FILE_NAMES = ['.anvilrc', 'anvil.config.json'] as const;
+
+/**
+ * Load Kindling configuration from the project root.
+ *
+ * Searches for `.anvilrc` or `anvil.config.json` in the given directory.
+ * Expects a JSON file with an optional `kindling` key containing the config.
+ *
+ * Returns the default (disabled) config if no file is found or if the
+ * `kindling` key is absent.
+ *
+ * @param projectRoot - Absolute path to the project root directory
+ * @returns Parsed and validated KindlingConfig
+ */
+export function loadKindlingConfig(projectRoot: string): KindlingConfig {
+  for (const fileName of CONFIG_FILE_NAMES) {
+    const filePath = join(projectRoot, fileName);
+
+    if (!existsSync(filePath)) {
+      continue;
+    }
+
+    try {
+      const raw = readFileSync(filePath, 'utf-8');
+      const parsed: unknown = JSON.parse(raw);
+
+      if (parsed === null || typeof parsed !== 'object') {
+        continue;
+      }
+
+      const record = parsed as Record<string, unknown>;
+
+      if (!('kindling' in record) || record['kindling'] === undefined) {
+        // Config file exists but has no kindling section
+        return DEFAULT_KINDLING_CONFIG;
+      }
+
+      const result = KindlingConfigSchema.safeParse(record['kindling']);
+
+      if (result.success) {
+        return result.data;
+      }
+
+      // Invalid config shape -- fall back to defaults rather than crashing
+      // The caller (service layer) will operate in disabled mode
+      return DEFAULT_KINDLING_CONFIG;
+    } catch {
+      // JSON parse error or read error -- fall back to defaults
+      return DEFAULT_KINDLING_CONFIG;
+    }
+  }
+
+  // No config file found
+  return DEFAULT_KINDLING_CONFIG;
+}
+
+/**
+ * Check whether a specific observation kind should be captured based on config.
+ *
+ * @param config - Kindling configuration
+ * @param kind - Observation kind string
+ * @returns true if the observation should be captured
+ */
+export function shouldCapture(config: KindlingConfig, kind: string): boolean {
+  if (!config.enabled) {
+    return false;
+  }
+
+  switch (kind) {
+    case 'session_start':
+    case 'session_end':
+      return config.capture.sessions;
+    case 'gate_evaluated':
+      return config.capture.gates;
+    case 'action_executed':
+      return config.capture.actions;
+    case 'plan_created':
+    case 'plan_edited':
+    case 'plan_approved':
+    case 'plan_rejected':
+      return config.capture.plans;
+    case 'human_input':
+      return config.capture.human_inputs;
+    case 'constraint_applied':
+      return config.capture.constraints;
+    case 'error':
+      return config.capture.errors;
+    default:
+      // Unknown kinds are captured by default when enabled
+      return true;
+  }
+}

package/src/emitters/action-emitter.ts

@@ -0,0 +1,90 @@
+/**
+ * Action Emitter (KINDLING-005)
+ *
+ * Emits action_executed observations when commands, tool invocations,
+ * file operations, or diff applications occur.
+ */
+
+import { randomUUID } from 'node:crypto';
+import type { KindlingService } from '../kindling-service.js';
+import type { ActionExecutedObservation } from '../observation-contract.js';
+import { createDebugger } from '../utils/debug.js';
+
+const debug = createDebugger('kindling');
+
+// =============================================================================
+// Input Types
+// =============================================================================
+
+/**
+ * Action execution details to be recorded
+ */
+export interface ActionDetails {
+  session_id: string;
+  action_type: 'command' | 'tool_invocation' | 'file_write' | 'file_delete' | 'diff_apply';
+  details: {
+    command?: string;
+    tool_name?: string;
+    file_paths?: string[];
+    diff_summary?: {
+      additions: number;
+      deletions: number;
+      files_changed: number;
+    };
+    working_directory: string;
+    environment_target?: string;
+  };
+  governed_by_gate_id?: string;
+  governed_by_plan_id?: string;
+  outcome: 'success' | 'failure' | 'partial';
+  exit_code?: number;
+  duration_ms: number;
+}
+
+// =============================================================================
+// Emitter
+// =============================================================================
+
+/**
+ * Emit an action_executed observation.
+ *
+ * @param service - KindlingService instance
+ * @param actionDetails - Action execution details
+ * @returns The generated action_id
+ */
+export function emitActionExecuted(service: KindlingService, actionDetails: ActionDetails): string {
+  const actionId = randomUUID();
+  debug('emitting action_executed', {
+    actionId,
+    actionType: actionDetails.action_type,
+    outcome: actionDetails.outcome,
+  });
+
+  const observation: ActionExecutedObservation = {
+    kind: 'action_executed',
+    session_id: actionDetails.session_id,
+    timestamp: new Date().toISOString(),
+    action_id: actionId,
+    action_type: actionDetails.action_type,
+    details: {
+      command: actionDetails.details.command,
+      tool_name: actionDetails.details.tool_name,
+      file_paths: actionDetails.details.file_paths,
+      diff_summary: actionDetails.details.diff_summary,
+      working_directory: actionDetails.details.working_directory,
+      environment_target: actionDetails.details.environment_target,
+    },
+    governed_by_gate_id: actionDetails.governed_by_gate_id,
+    governed_by_plan_id: actionDetails.governed_by_plan_id,
+    outcome: actionDetails.outcome,
+    exit_code: actionDetails.exit_code,
+    duration_ms: actionDetails.duration_ms,
+  };
+
+  // Fire-and-forget
+  service.emit(observation).catch(() => {
+    // Silently swallow
+  });
+
+  return actionId;
+}

package/src/emitters/constraint-emitter.ts

@@ -0,0 +1,73 @@
+/**
+ * Constraint Emitter (KINDLING-007b)
+ *
+ * Emits constraint_applied observations when Anvil prevents an action
+ * due to policy, scope, environment, or approval requirements.
+ */
+
+import { randomUUID } from 'node:crypto';
+import type { KindlingService } from '../kindling-service.js';
+import type { ConstraintAppliedObservation } from '../observation-contract.js';
+
+// =============================================================================
+// Input Types
+// =============================================================================
+
+/**
+ * Constraint application details to be recorded
+ */
+export interface ConstraintDetails {
+  session_id: string;
+  constraint_type: 'policy' | 'rule' | 'scope' | 'environment' | 'approval_required';
+  prevented_action: {
+    action_type: string;
+    action_target?: string;
+  };
+  reason: string;
+  scope?: string;
+  environment?: string;
+  options_available?: string[];
+  options_allowed?: string[];
+}
+
+// =============================================================================
+// Emitter
+// =============================================================================
+
+/**
+ * Emit a constraint_applied observation.
+ *
+ * @param service - KindlingService instance
+ * @param constraint - Constraint application details
+ * @returns The generated constraint_id
+ */
+export function emitConstraintApplied(
+  service: KindlingService,
+  constraint: ConstraintDetails
+): string {
+  const constraintId = randomUUID();
+
+  const observation: ConstraintAppliedObservation = {
+    kind: 'constraint_applied',
+    session_id: constraint.session_id,
+    timestamp: new Date().toISOString(),
+    constraint_id: constraintId,
+    constraint_type: constraint.constraint_type,
+    prevented_action: {
+      action_type: constraint.prevented_action.action_type,
+      action_target: constraint.prevented_action.action_target,
+    },
+    reason: constraint.reason,
+    scope: constraint.scope,
+    environment: constraint.environment,
+    options_available: constraint.options_available,
+    options_allowed: constraint.options_allowed,
+  };
+
+  // Fire-and-forget
+  service.emit(observation).catch(() => {
+    // Silently swallow
+  });
+
+  return constraintId;
+}

package/src/emitters/error-emitter.ts

@@ -0,0 +1,86 @@
+/**
+ * Error Emitter (KINDLING-008)
+ *
+ * Emits error observations when failures occur.
+ * "Errors are not noise, they are data."
+ */
+
+import { randomUUID } from 'node:crypto';
+import type { KindlingService } from '../kindling-service.js';
+import type { ErrorObservation } from '../observation-contract.js';
+import { createDebugger } from '../utils/debug.js';
+
+const debug = createDebugger('kindling');
+
+// =============================================================================
+// Input Types
+// =============================================================================
+
+/**
+ * Error details to be recorded
+ */
+export interface ErrorDetails {
+  session_id: string;
+  error_type:
+    | 'command_failure'
+    | 'tool_error'
+    | 'aborted_execution'
+    | 'partial_state'
+    | 'validation_failure';
+  context: {
+    component: string;
+    action_id?: string;
+    gate_id?: string;
+  };
+  error_message: string;
+  error_code?: string;
+  exit_code?: number;
+  recoverable: boolean;
+  partial_state_description?: string;
+}
+
+// =============================================================================
+// Emitter
+// =============================================================================
+
+/**
+ * Emit an error observation.
+ *
+ * @param service - KindlingService instance
+ * @param errorDetails - Error details
+ * @returns The generated error_id
+ */
+export function emitError(service: KindlingService, errorDetails: ErrorDetails): string {
+  const errorId = randomUUID();
+  debug('emitting error observation', {
+    errorId,
+    errorType: errorDetails.error_type,
+    component: errorDetails.context.component,
+    recoverable: errorDetails.recoverable,
+  });
+
+  const observation: ErrorObservation = {
+    kind: 'error',
+    session_id: errorDetails.session_id,
+    timestamp: new Date().toISOString(),
+    error_id: errorId,
+    error_type: errorDetails.error_type,
+    context: {
+      component: errorDetails.context.component,
+      action_id: errorDetails.context.action_id,
+      gate_id: errorDetails.context.gate_id,
+    },
+    error_message: errorDetails.error_message,
+    error_code: errorDetails.error_code,
+    exit_code: errorDetails.exit_code,
+    recoverable: errorDetails.recoverable,
+    partial_state_description: errorDetails.partial_state_description,
+  };
+
+  // Fire-and-forget
+  service.emit(observation).catch(() => {
+    // Silently swallow
+  });
+
+  return errorId;
+}