@claude-flow/cli 3.32.25 → 3.32.29

package/dist/src/memory/memory-initializer.d.ts

@@ -8,6 +8,17 @@
  *
  * @module v3/cli/memory-initializer
  */
+/**
+ * ADR-323 — typed memory provenance. Distinguishes WHO/WHAT wrote a memory
+ * entry (a user's stated claim vs an agent's own output vs a tool result vs
+ * a raw system observation) so retrieval can filter by trust level instead
+ * of treating every entry in a shared namespace as equally authoritative.
+ * `unknown` is the backward-compatible default for entries written before
+ * this field existed, and for callers that don't pass one.
+ */
+export declare const PROVENANCE_TYPES: readonly ["user_claim", "agent_output", "system_observation", "tool_result", "unknown"];
+export type ProvenanceType = (typeof PROVENANCE_TYPES)[number];
+export declare function isValidProvenanceType(value: unknown): value is ProvenanceType;
 export declare function getMemoryRoot(): string;
 /** For tests + the `memory configure` flow that mutates the config at runtime. */
 export declare function _resetMemoryRootCache(): void;
@@ -24,7 +35,7 @@ export declare function resolveDbPath(cliFlag?: string): string;
  * Enhanced schema with pattern confidence, temporal decay, versioning
  * Vector embeddings enabled for semantic search
  */
-export declare const MEMORY_SCHEMA_V3 = "\n-- RuFlo V3 Memory Database\n-- Version: 3.0.0\n-- Features: Pattern learning, vector embeddings, temporal decay, migration tracking\n\nPRAGMA journal_mode = WAL;\nPRAGMA synchronous = NORMAL;\nPRAGMA foreign_keys = ON;\n\n-- ============================================\n-- CORE MEMORY TABLES\n-- ============================================\n\n-- Memory entries (main storage)\nCREATE TABLE IF NOT EXISTS memory_entries (\n  id TEXT PRIMARY KEY,\n  key TEXT NOT NULL,\n  namespace TEXT DEFAULT 'default',\n  content TEXT NOT NULL,\n  type TEXT DEFAULT 'semantic' CHECK(type IN ('semantic', 'episodic', 'procedural', 'working', 'pattern')),\n\n  -- Vector embedding for semantic search (stored as JSON array)\n  embedding TEXT,\n  embedding_model TEXT DEFAULT 'local',\n  embedding_dimensions INTEGER,\n\n  -- Metadata\n  tags TEXT, -- JSON array\n  metadata TEXT, -- JSON object\n  owner_id TEXT,\n\n  -- Timestamps\n  created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),\n  updated_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),\n  expires_at INTEGER,\n  last_accessed_at INTEGER,\n\n  -- Access tracking for hot/cold detection\n  access_count INTEGER DEFAULT 0,\n\n  -- Status\n  status TEXT DEFAULT 'active' CHECK(status IN ('active', 'archived', 'deleted')),\n\n  UNIQUE(namespace, key)\n);\n\n-- Indexes for memory entries\nCREATE INDEX IF NOT EXISTS idx_memory_namespace ON memory_entries(namespace);\nCREATE INDEX IF NOT EXISTS idx_memory_key ON memory_entries(key);\nCREATE INDEX IF NOT EXISTS idx_memory_type ON memory_entries(type);\nCREATE INDEX IF NOT EXISTS idx_memory_status ON memory_entries(status);\nCREATE INDEX IF NOT EXISTS idx_memory_created ON memory_entries(created_at);\nCREATE INDEX IF NOT EXISTS idx_memory_accessed ON memory_entries(last_accessed_at);\nCREATE INDEX IF NOT EXISTS idx_memory_owner ON memory_entries(owner_id);\n\n-- ============================================\n-- PATTERN LEARNING TABLES\n-- ============================================\n\n-- Learned patterns with confidence scoring and versioning\nCREATE TABLE IF NOT EXISTS patterns (\n  id TEXT PRIMARY KEY,\n\n  -- Pattern identification\n  name TEXT NOT NULL,\n  pattern_type TEXT NOT NULL CHECK(pattern_type IN (\n    'task-routing', 'error-recovery', 'optimization', 'learning',\n    'coordination', 'prediction', 'code-pattern', 'workflow'\n  )),\n\n  -- Pattern definition\n  condition TEXT NOT NULL, -- Regex or semantic match\n  action TEXT NOT NULL, -- What to do when pattern matches\n  description TEXT,\n\n  -- Confidence scoring (0.0 - 1.0)\n  confidence REAL DEFAULT 0.5,\n  success_count INTEGER DEFAULT 0,\n  failure_count INTEGER DEFAULT 0,\n\n  -- Temporal decay\n  decay_rate REAL DEFAULT 0.01, -- How fast confidence decays\n  half_life_days INTEGER DEFAULT 30, -- Days until confidence halves without use\n\n  -- Vector embedding for semantic pattern matching\n  embedding TEXT,\n  embedding_dimensions INTEGER,\n\n  -- Versioning\n  version INTEGER DEFAULT 1,\n  parent_id TEXT REFERENCES patterns(id),\n\n  -- Metadata\n  tags TEXT, -- JSON array\n  metadata TEXT, -- JSON object\n  source TEXT, -- Where the pattern was learned from\n\n  -- Timestamps\n  created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),\n  updated_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),\n  last_matched_at INTEGER,\n  last_success_at INTEGER,\n  last_failure_at INTEGER,\n\n  -- Status\n  status TEXT DEFAULT 'active' CHECK(status IN ('active', 'archived', 'deprecated', 'experimental'))\n);\n\n-- Indexes for patterns\nCREATE INDEX IF NOT EXISTS idx_patterns_type ON patterns(pattern_type);\nCREATE INDEX IF NOT EXISTS idx_patterns_confidence ON patterns(confidence DESC);\nCREATE INDEX IF NOT EXISTS idx_patterns_status ON patterns(status);\nCREATE INDEX IF NOT EXISTS idx_patterns_last_matched ON patterns(last_matched_at);\n\n-- Pattern evolution history (for versioning)\nCREATE TABLE IF NOT EXISTS pattern_history (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  pattern_id TEXT NOT NULL REFERENCES patterns(id),\n  version INTEGER NOT NULL,\n\n  -- Snapshot of pattern state\n  confidence REAL,\n  success_count INTEGER,\n  failure_count INTEGER,\n  condition TEXT,\n  action TEXT,\n\n  -- What changed\n  change_type TEXT CHECK(change_type IN ('created', 'updated', 'success', 'failure', 'decay', 'merged', 'split')),\n  change_reason TEXT,\n\n  created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000)\n);\n\nCREATE INDEX IF NOT EXISTS idx_pattern_history_pattern ON pattern_history(pattern_id);\n\n-- ============================================\n-- LEARNING & TRAJECTORY TABLES\n-- ============================================\n\n-- Learning trajectories (SONA integration)\nCREATE TABLE IF NOT EXISTS trajectories (\n  id TEXT PRIMARY KEY,\n  session_id TEXT,\n\n  -- Trajectory state\n  status TEXT DEFAULT 'active' CHECK(status IN ('active', 'completed', 'failed', 'abandoned')),\n  verdict TEXT CHECK(verdict IN ('success', 'failure', 'partial', NULL)),\n\n  -- Context\n  task TEXT,\n  context TEXT, -- JSON object\n\n  -- Metrics\n  total_steps INTEGER DEFAULT 0,\n  total_reward REAL DEFAULT 0,\n\n  -- Timestamps\n  started_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),\n  ended_at INTEGER,\n\n  -- Reference to extracted pattern (if any)\n  extracted_pattern_id TEXT REFERENCES patterns(id)\n);\n\n-- Trajectory steps\nCREATE TABLE IF NOT EXISTS trajectory_steps (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  trajectory_id TEXT NOT NULL REFERENCES trajectories(id),\n  step_number INTEGER NOT NULL,\n\n  -- Step data\n  action TEXT NOT NULL,\n  observation TEXT,\n  reward REAL DEFAULT 0,\n\n  -- Metadata\n  metadata TEXT, -- JSON object\n\n  created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000)\n);\n\nCREATE INDEX IF NOT EXISTS idx_steps_trajectory ON trajectory_steps(trajectory_id);\n\n-- ============================================\n-- MIGRATION STATE TRACKING\n-- ============================================\n\n-- Migration state (for resume capability)\nCREATE TABLE IF NOT EXISTS migration_state (\n  id TEXT PRIMARY KEY,\n  migration_type TEXT NOT NULL, -- 'v2-to-v3', 'pattern', 'memory', etc.\n\n  -- Progress tracking\n  status TEXT DEFAULT 'pending' CHECK(status IN ('pending', 'in_progress', 'completed', 'failed', 'rolled_back')),\n  total_items INTEGER DEFAULT 0,\n  processed_items INTEGER DEFAULT 0,\n  failed_items INTEGER DEFAULT 0,\n  skipped_items INTEGER DEFAULT 0,\n\n  -- Current position (for resume)\n  current_batch INTEGER DEFAULT 0,\n  last_processed_id TEXT,\n\n  -- Source/destination info\n  source_path TEXT,\n  source_type TEXT,\n  destination_path TEXT,\n\n  -- Backup info\n  backup_path TEXT,\n  backup_created_at INTEGER,\n\n  -- Error tracking\n  last_error TEXT,\n  errors TEXT, -- JSON array of errors\n\n  -- Timestamps\n  started_at INTEGER,\n  completed_at INTEGER,\n  created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),\n  updated_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000)\n);\n\n-- ============================================\n-- SESSION MANAGEMENT\n-- ============================================\n\n-- Sessions for context persistence\nCREATE TABLE IF NOT EXISTS sessions (\n  id TEXT PRIMARY KEY,\n\n  -- Session state\n  state TEXT NOT NULL, -- JSON object with full session state\n  status TEXT DEFAULT 'active' CHECK(status IN ('active', 'paused', 'completed', 'expired')),\n\n  -- Context\n  project_path TEXT,\n  branch TEXT,\n\n  -- Metrics\n  tasks_completed INTEGER DEFAULT 0,\n  patterns_learned INTEGER DEFAULT 0,\n\n  -- Timestamps\n  created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),\n  updated_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),\n  expires_at INTEGER\n);\n\n-- ============================================\n-- VECTOR INDEX METADATA (for HNSW)\n-- ============================================\n\n-- Track HNSW index state\nCREATE TABLE IF NOT EXISTS vector_indexes (\n  id TEXT PRIMARY KEY,\n  name TEXT NOT NULL UNIQUE,\n\n  -- Index configuration\n  dimensions INTEGER NOT NULL,\n  metric TEXT DEFAULT 'cosine' CHECK(metric IN ('cosine', 'euclidean', 'dot')),\n\n  -- HNSW parameters\n  hnsw_m INTEGER DEFAULT 16,\n  hnsw_ef_construction INTEGER DEFAULT 200,\n  hnsw_ef_search INTEGER DEFAULT 100,\n\n  -- Quantization\n  quantization_type TEXT CHECK(quantization_type IN ('none', 'scalar', 'product')),\n  quantization_bits INTEGER DEFAULT 8,\n\n  -- Statistics\n  total_vectors INTEGER DEFAULT 0,\n  last_rebuild_at INTEGER,\n\n  created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),\n  updated_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000)\n);\n\n-- ============================================\n-- GRAPH EDGES (ADR-130 Phase 1)\n-- Unified knowledge graph backend \u2014 sql.js canonical store\n-- ============================================\n\n-- Unified graph edges table (ADR-130)\n-- Node IDs use domain-prefixed format: {domain}:{uuid}\n-- where domain in (mem, agent, task, entity, span, pattern)\nCREATE TABLE IF NOT EXISTS graph_edges (\n  id              TEXT PRIMARY KEY,          -- edge-{uuid}\n  source_id       TEXT NOT NULL,             -- domain-prefixed node ID\n  target_id       TEXT NOT NULL,             -- domain-prefixed node ID\n  relation        TEXT NOT NULL,             -- e.g. \"caused\", \"depends-on\", \"imports\"\n  weight          REAL DEFAULT 1.0,\n  -- Temporal / reliability semantics (ADR-130 \u00A7\"graph that forgets\" property)\n  confidence      REAL DEFAULT 1.0,          -- [0,1]; updated by JUDGE step\n  decay_rate      REAL DEFAULT 0.0,          -- per-day exponential decay applied at read time\n  last_reinforced TEXT,                      -- ISO-8601; set when CONSOLIDATE re-touches edge\n  witness_id      TEXT,                      -- FK to verification/witness-fixes.json (ADR-103)\n  -- Embedding storage: \"inline:{base64}\" | \"vector_indexes:{id}\" | NULL\n  embedding_ref   TEXT,\n  metadata        TEXT,                      -- JSON blob for plugin-specific fields\n  created_at      TEXT NOT NULL\n);\n\nCREATE INDEX IF NOT EXISTS idx_graph_edges_source    ON graph_edges (source_id);\nCREATE INDEX IF NOT EXISTS idx_graph_edges_target    ON graph_edges (target_id);\nCREATE INDEX IF NOT EXISTS idx_graph_edges_relation  ON graph_edges (relation);\nCREATE INDEX IF NOT EXISTS idx_graph_edges_reinforced ON graph_edges (last_reinforced);\n\n-- ============================================\n-- SYSTEM METADATA\n-- ============================================\n\nCREATE TABLE IF NOT EXISTS metadata (\n  key TEXT PRIMARY KEY,\n  value TEXT NOT NULL,\n  updated_at INTEGER DEFAULT (strftime('%s', 'now') * 1000)\n);\n";
+export declare const MEMORY_SCHEMA_V3 = "\n-- RuFlo V3 Memory Database\n-- Version: 3.0.0\n-- Features: Pattern learning, vector embeddings, temporal decay, migration tracking\n\nPRAGMA journal_mode = WAL;\nPRAGMA synchronous = NORMAL;\nPRAGMA foreign_keys = ON;\n\n-- ============================================\n-- CORE MEMORY TABLES\n-- ============================================\n\n-- Memory entries (main storage)\nCREATE TABLE IF NOT EXISTS memory_entries (\n  id TEXT PRIMARY KEY,\n  key TEXT NOT NULL,\n  namespace TEXT DEFAULT 'default',\n  content TEXT NOT NULL,\n  type TEXT DEFAULT 'semantic' CHECK(type IN ('semantic', 'episodic', 'procedural', 'working', 'pattern')),\n\n  -- Vector embedding for semantic search (stored as JSON array)\n  embedding TEXT,\n  embedding_model TEXT DEFAULT 'local',\n  embedding_dimensions INTEGER,\n\n  -- Metadata\n  tags TEXT, -- JSON array\n  metadata TEXT, -- JSON object\n  owner_id TEXT,\n\n  -- ADR-323: who/what produced this entry \u2014 lets shared-namespace retrieval\n  -- filter by trust level instead of conflating a user's stated claim with\n  -- an agent's own output or a raw tool/system observation.\n  provenance_type TEXT DEFAULT 'unknown' CHECK(provenance_type IN (\n    'user_claim', 'agent_output', 'system_observation', 'tool_result', 'unknown'\n  )),\n\n  -- Timestamps\n  created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),\n  updated_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),\n  expires_at INTEGER,\n  last_accessed_at INTEGER,\n\n  -- Access tracking for hot/cold detection\n  access_count INTEGER DEFAULT 0,\n\n  -- Status\n  status TEXT DEFAULT 'active' CHECK(status IN ('active', 'archived', 'deleted')),\n\n  UNIQUE(namespace, key)\n);\n\n-- Indexes for memory entries\nCREATE INDEX IF NOT EXISTS idx_memory_namespace ON memory_entries(namespace);\nCREATE INDEX IF NOT EXISTS idx_memory_key ON memory_entries(key);\nCREATE INDEX IF NOT EXISTS idx_memory_type ON memory_entries(type);\nCREATE INDEX IF NOT EXISTS idx_memory_status ON memory_entries(status);\nCREATE INDEX IF NOT EXISTS idx_memory_created ON memory_entries(created_at);\nCREATE INDEX IF NOT EXISTS idx_memory_accessed ON memory_entries(last_accessed_at);\nCREATE INDEX IF NOT EXISTS idx_memory_owner ON memory_entries(owner_id);\n\n-- ============================================\n-- PATTERN LEARNING TABLES\n-- ============================================\n\n-- Learned patterns with confidence scoring and versioning\nCREATE TABLE IF NOT EXISTS patterns (\n  id TEXT PRIMARY KEY,\n\n  -- Pattern identification\n  name TEXT NOT NULL,\n  pattern_type TEXT NOT NULL CHECK(pattern_type IN (\n    'task-routing', 'error-recovery', 'optimization', 'learning',\n    'coordination', 'prediction', 'code-pattern', 'workflow'\n  )),\n\n  -- Pattern definition\n  condition TEXT NOT NULL, -- Regex or semantic match\n  action TEXT NOT NULL, -- What to do when pattern matches\n  description TEXT,\n\n  -- Confidence scoring (0.0 - 1.0)\n  confidence REAL DEFAULT 0.5,\n  success_count INTEGER DEFAULT 0,\n  failure_count INTEGER DEFAULT 0,\n\n  -- Temporal decay\n  decay_rate REAL DEFAULT 0.01, -- How fast confidence decays\n  half_life_days INTEGER DEFAULT 30, -- Days until confidence halves without use\n\n  -- Vector embedding for semantic pattern matching\n  embedding TEXT,\n  embedding_dimensions INTEGER,\n\n  -- Versioning\n  version INTEGER DEFAULT 1,\n  parent_id TEXT REFERENCES patterns(id),\n\n  -- Metadata\n  tags TEXT, -- JSON array\n  metadata TEXT, -- JSON object\n  source TEXT, -- Where the pattern was learned from\n\n  -- Timestamps\n  created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),\n  updated_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),\n  last_matched_at INTEGER,\n  last_success_at INTEGER,\n  last_failure_at INTEGER,\n\n  -- Status\n  status TEXT DEFAULT 'active' CHECK(status IN ('active', 'archived', 'deprecated', 'experimental'))\n);\n\n-- Indexes for patterns\nCREATE INDEX IF NOT EXISTS idx_patterns_type ON patterns(pattern_type);\nCREATE INDEX IF NOT EXISTS idx_patterns_confidence ON patterns(confidence DESC);\nCREATE INDEX IF NOT EXISTS idx_patterns_status ON patterns(status);\nCREATE INDEX IF NOT EXISTS idx_patterns_last_matched ON patterns(last_matched_at);\n\n-- Pattern evolution history (for versioning)\nCREATE TABLE IF NOT EXISTS pattern_history (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  pattern_id TEXT NOT NULL REFERENCES patterns(id),\n  version INTEGER NOT NULL,\n\n  -- Snapshot of pattern state\n  confidence REAL,\n  success_count INTEGER,\n  failure_count INTEGER,\n  condition TEXT,\n  action TEXT,\n\n  -- What changed\n  change_type TEXT CHECK(change_type IN ('created', 'updated', 'success', 'failure', 'decay', 'merged', 'split')),\n  change_reason TEXT,\n\n  created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000)\n);\n\nCREATE INDEX IF NOT EXISTS idx_pattern_history_pattern ON pattern_history(pattern_id);\n\n-- ============================================\n-- LEARNING & TRAJECTORY TABLES\n-- ============================================\n\n-- Learning trajectories (SONA integration)\nCREATE TABLE IF NOT EXISTS trajectories (\n  id TEXT PRIMARY KEY,\n  session_id TEXT,\n\n  -- Trajectory state\n  status TEXT DEFAULT 'active' CHECK(status IN ('active', 'completed', 'failed', 'abandoned')),\n  verdict TEXT CHECK(verdict IN ('success', 'failure', 'partial', NULL)),\n\n  -- Context\n  task TEXT,\n  context TEXT, -- JSON object\n\n  -- Metrics\n  total_steps INTEGER DEFAULT 0,\n  total_reward REAL DEFAULT 0,\n\n  -- Timestamps\n  started_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),\n  ended_at INTEGER,\n\n  -- Reference to extracted pattern (if any)\n  extracted_pattern_id TEXT REFERENCES patterns(id)\n);\n\n-- Trajectory steps\nCREATE TABLE IF NOT EXISTS trajectory_steps (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  trajectory_id TEXT NOT NULL REFERENCES trajectories(id),\n  step_number INTEGER NOT NULL,\n\n  -- Step data\n  action TEXT NOT NULL,\n  observation TEXT,\n  reward REAL DEFAULT 0,\n\n  -- Metadata\n  metadata TEXT, -- JSON object\n\n  created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000)\n);\n\nCREATE INDEX IF NOT EXISTS idx_steps_trajectory ON trajectory_steps(trajectory_id);\n\n-- ============================================\n-- MIGRATION STATE TRACKING\n-- ============================================\n\n-- Migration state (for resume capability)\nCREATE TABLE IF NOT EXISTS migration_state (\n  id TEXT PRIMARY KEY,\n  migration_type TEXT NOT NULL, -- 'v2-to-v3', 'pattern', 'memory', etc.\n\n  -- Progress tracking\n  status TEXT DEFAULT 'pending' CHECK(status IN ('pending', 'in_progress', 'completed', 'failed', 'rolled_back')),\n  total_items INTEGER DEFAULT 0,\n  processed_items INTEGER DEFAULT 0,\n  failed_items INTEGER DEFAULT 0,\n  skipped_items INTEGER DEFAULT 0,\n\n  -- Current position (for resume)\n  current_batch INTEGER DEFAULT 0,\n  last_processed_id TEXT,\n\n  -- Source/destination info\n  source_path TEXT,\n  source_type TEXT,\n  destination_path TEXT,\n\n  -- Backup info\n  backup_path TEXT,\n  backup_created_at INTEGER,\n\n  -- Error tracking\n  last_error TEXT,\n  errors TEXT, -- JSON array of errors\n\n  -- Timestamps\n  started_at INTEGER,\n  completed_at INTEGER,\n  created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),\n  updated_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000)\n);\n\n-- ============================================\n-- SESSION MANAGEMENT\n-- ============================================\n\n-- Sessions for context persistence\nCREATE TABLE IF NOT EXISTS sessions (\n  id TEXT PRIMARY KEY,\n\n  -- Session state\n  state TEXT NOT NULL, -- JSON object with full session state\n  status TEXT DEFAULT 'active' CHECK(status IN ('active', 'paused', 'completed', 'expired')),\n\n  -- Context\n  project_path TEXT,\n  branch TEXT,\n\n  -- Metrics\n  tasks_completed INTEGER DEFAULT 0,\n  patterns_learned INTEGER DEFAULT 0,\n\n  -- Timestamps\n  created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),\n  updated_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),\n  expires_at INTEGER\n);\n\n-- ============================================\n-- VECTOR INDEX METADATA (for HNSW)\n-- ============================================\n\n-- Track HNSW index state\nCREATE TABLE IF NOT EXISTS vector_indexes (\n  id TEXT PRIMARY KEY,\n  name TEXT NOT NULL UNIQUE,\n\n  -- Index configuration\n  dimensions INTEGER NOT NULL,\n  metric TEXT DEFAULT 'cosine' CHECK(metric IN ('cosine', 'euclidean', 'dot')),\n\n  -- HNSW parameters\n  hnsw_m INTEGER DEFAULT 16,\n  hnsw_ef_construction INTEGER DEFAULT 200,\n  hnsw_ef_search INTEGER DEFAULT 100,\n\n  -- Quantization\n  quantization_type TEXT CHECK(quantization_type IN ('none', 'scalar', 'product')),\n  quantization_bits INTEGER DEFAULT 8,\n\n  -- Statistics\n  total_vectors INTEGER DEFAULT 0,\n  last_rebuild_at INTEGER,\n\n  created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),\n  updated_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000)\n);\n\n-- ============================================\n-- GRAPH EDGES (ADR-130 Phase 1)\n-- Unified knowledge graph backend \u2014 sql.js canonical store\n-- ============================================\n\n-- Unified graph edges table (ADR-130)\n-- Node IDs use domain-prefixed format: {domain}:{uuid}\n-- where domain in (mem, agent, task, entity, span, pattern)\nCREATE TABLE IF NOT EXISTS graph_edges (\n  id              TEXT PRIMARY KEY,          -- edge-{uuid}\n  source_id       TEXT NOT NULL,             -- domain-prefixed node ID\n  target_id       TEXT NOT NULL,             -- domain-prefixed node ID\n  relation        TEXT NOT NULL,             -- e.g. \"caused\", \"depends-on\", \"imports\"\n  weight          REAL DEFAULT 1.0,\n  -- Temporal / reliability semantics (ADR-130 \u00A7\"graph that forgets\" property)\n  confidence      REAL DEFAULT 1.0,          -- [0,1]; updated by JUDGE step\n  decay_rate      REAL DEFAULT 0.0,          -- per-day exponential decay applied at read time\n  last_reinforced TEXT,                      -- ISO-8601; set when CONSOLIDATE re-touches edge\n  witness_id      TEXT,                      -- FK to verification/witness-fixes.json (ADR-103)\n  -- Embedding storage: \"inline:{base64}\" | \"vector_indexes:{id}\" | NULL\n  embedding_ref   TEXT,\n  metadata        TEXT,                      -- JSON blob for plugin-specific fields\n  created_at      TEXT NOT NULL\n);\n\nCREATE INDEX IF NOT EXISTS idx_graph_edges_source    ON graph_edges (source_id);\nCREATE INDEX IF NOT EXISTS idx_graph_edges_target    ON graph_edges (target_id);\nCREATE INDEX IF NOT EXISTS idx_graph_edges_relation  ON graph_edges (relation);\nCREATE INDEX IF NOT EXISTS idx_graph_edges_reinforced ON graph_edges (last_reinforced);\n\n-- ============================================\n-- SYSTEM METADATA\n-- ============================================\n\nCREATE TABLE IF NOT EXISTS metadata (\n  key TEXT PRIMARY KEY,\n  value TEXT NOT NULL,\n  updated_at INTEGER DEFAULT (strftime('%s', 'now') * 1000)\n);\n";
 interface HNSWEntry {
     id: string;
     key: string;
@@ -419,6 +430,8 @@ export declare function storeEntry(options: {
     ttl?: number;
     dbPath?: string;
     upsert?: boolean;
+    /** ADR-323: defaults to 'unknown' when omitted. */
+    provenanceType?: string;
 }): Promise<{
     success: boolean;
     id: string;
@@ -438,6 +451,10 @@ export declare function searchEntries(options: {
     limit?: number;
     threshold?: number;
     dbPath?: string;
+    /** ADR-323: restrict results to these provenance types (e.g. exclude
+     *  'user_claim' when retrieving for fact-checking, per MemSyco-Bench's
+     *  sycophancy finding). Omit/empty = no filtering (all types). */
+    provenanceFilter?: string[];
 }): Promise<{
     success: boolean;
     results: {
@@ -446,6 +463,7 @@ export declare function searchEntries(options: {
         content: string;
         score: number;
         namespace: string;
+        provenanceType?: string;
     }[];
     searchTime: number;
     error?: string;
@@ -460,6 +478,8 @@ export declare function listEntries(options: {
     dbPath?: string;
     /** #2073: When true, include the entry's full `content` string in each result. */
     includeContent?: boolean;
+    /** ADR-323: restrict rows to these provenance types. */
+    provenanceFilter?: string[];
 }): Promise<{
     success: boolean;
     entries: {
@@ -473,6 +493,7 @@ export declare function listEntries(options: {
         hasEmbedding: boolean;
         /** #2073: Present when `includeContent: true` was requested. */
         content?: string;
+        provenanceType?: string;
     }[];
     total: number;
     error?: string;

package/dist/src/memory/memory-initializer.js

@@ -13,6 +13,24 @@ import * as path from 'path';
 import { createRequire } from 'node:module';
 import { readFileMaybeEncrypted, writeFileAtomic, writeFileRestricted } from '../fs-secure.js';
 import { restoreMemoryDbFromBackup } from '../services/memory-backup.js';
+/**
+ * ADR-323 — typed memory provenance. Distinguishes WHO/WHAT wrote a memory
+ * entry (a user's stated claim vs an agent's own output vs a tool result vs
+ * a raw system observation) so retrieval can filter by trust level instead
+ * of treating every entry in a shared namespace as equally authoritative.
+ * `unknown` is the backward-compatible default for entries written before
+ * this field existed, and for callers that don't pass one.
+ */
+export const PROVENANCE_TYPES = [
+    'user_claim',
+    'agent_output',
+    'system_observation',
+    'tool_result',
+    'unknown',
+];
+export function isValidProvenanceType(value) {
+    return typeof value === 'string' && PROVENANCE_TYPES.includes(value);
+}
 /**
  * #2356 — cached, synchronous capability probe for @ruvector/core. `getHNSWStatus`
  * is sync and is called by `neural status` in a fresh process that never warms
@@ -193,6 +211,13 @@ CREATE TABLE IF NOT EXISTS memory_entries (
   metadata TEXT, -- JSON object
   owner_id TEXT,
 
+  -- ADR-323: who/what produced this entry — lets shared-namespace retrieval
+  -- filter by trust level instead of conflating a user's stated claim with
+  -- an agent's own output or a raw tool/system observation.
+  provenance_type TEXT DEFAULT 'unknown' CHECK(provenance_type IN (
+    'user_claim', 'agent_output', 'system_observation', 'tool_result', 'unknown'
+  )),
+
   -- Timestamps
   created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),
   updated_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),
@@ -1017,7 +1042,13 @@ export async function ensureSchemaColumns(dbPath) {
             { name: 'expires_at', definition: 'expires_at INTEGER' },
             { name: 'last_accessed_at', definition: 'last_accessed_at INTEGER' },
             { name: 'access_count', definition: 'access_count INTEGER DEFAULT 0' },
-            { name: 'status', definition: "status TEXT DEFAULT 'active'" }
+            { name: 'status', definition: "status TEXT DEFAULT 'active'" },
+            // ADR-323: older DBs predate provenance typing entirely — backfilled
+            // as 'unknown' via the DEFAULT, same convention as 'type'/'status'
+            // above (no CHECK on the ALTER; enforcement happens in storeEntry()/
+            // bridgeStoreEntry() so an invalid value gets a CLI-friendly error
+            // instead of a raw SQLite constraint failure).
+            { name: 'provenance_type', definition: "provenance_type TEXT DEFAULT 'unknown'" }
         ];
         let modified = false;
         for (const col of requiredColumns) {
@@ -2305,6 +2336,16 @@ export async function verifyMemoryInit(dbPath, options) {
  * This bypasses MCP and writes directly to the database
  */
 export async function storeEntry(options) {
+    // ADR-323: validate before touching either backend so an invalid value
+    // gets one clear error instead of a raw SQLite CHECK-constraint failure
+    // from whichever path (bridge vs sql.js) happens to run.
+    if (options.provenanceType !== undefined && !isValidProvenanceType(options.provenanceType)) {
+        return {
+            success: false,
+            id: '',
+            error: `Invalid provenance type "${options.provenanceType}" — must be one of: ${PROVENANCE_TYPES.join(', ')}`,
+        };
+    }
     // ADR-053: Try AgentDB v3 bridge first
     const bridge = await getBridge();
     if (bridge) {
@@ -2324,7 +2365,7 @@ export async function storeEntry(options) {
         }
     }
     // Fallback: raw sql.js
-    const { key, value, namespace = 'default', generateEmbeddingFlag = true, tags = [], ttl, dbPath: customPath, upsert = false } = options;
+    const { key, value, namespace = 'default', generateEmbeddingFlag = true, tags = [], ttl, dbPath: customPath, upsert = false, provenanceType } = options;
     const swarmDir = getMemoryRoot();
     const dbPath = customPath ? path.resolve(customPath) : path.join(swarmDir, 'memory.db');
     try {
@@ -2353,6 +2394,19 @@ export async function storeEntry(options) {
         const SQL = await initSqlJs();
         const fileBuffer = readFileMaybeEncrypted(dbPath, null);
         const db = new SQL.Database(fileBuffer);
+        let persistedProvenance = provenanceType ?? 'unknown';
+        if (upsert && provenanceType === undefined) {
+            try {
+                const stmt = db.prepare('SELECT provenance_type FROM memory_entries WHERE namespace = ? AND key = ? LIMIT 1');
+                stmt.bind([namespace, key]);
+                if (stmt.step()) {
+                    const existingType = stmt.get()[0];
+                    persistedProvenance = isValidProvenanceType(existingType) ? existingType : 'unknown';
+                }
+                stmt.free();
+            }
+            catch { /* legacy schema or new row — keep unknown */ }
+        }
         const id = `entry_${Date.now()}_${Math.random().toString(36).substring(7)}`;
         const now = Date.now();
         // Generate embedding if requested
@@ -2379,13 +2433,13 @@ export async function storeEntry(options) {
             ? `INSERT OR REPLACE INTO memory_entries (
           id, key, namespace, content, type,
           embedding, embedding_dimensions, embedding_model,
-          tags, metadata, created_at, updated_at, expires_at, status
-        ) VALUES (?, ?, ?, ?, 'semantic', ?, ?, ?, ?, ?, ?, ?, ?, 'active')`
+          tags, metadata, provenance_type, created_at, updated_at, expires_at, status
+        ) VALUES (?, ?, ?, ?, 'semantic', ?, ?, ?, ?, ?, ?, ?, ?, ?, 'active')`
             : `INSERT INTO memory_entries (
           id, key, namespace, content, type,
           embedding, embedding_dimensions, embedding_model,
-          tags, metadata, created_at, updated_at, expires_at, status
-        ) VALUES (?, ?, ?, ?, 'semantic', ?, ?, ?, ?, ?, ?, ?, ?, 'active')`;
+          tags, metadata, provenance_type, created_at, updated_at, expires_at, status
+        ) VALUES (?, ?, ?, ?, 'semantic', ?, ?, ?, ?, ?, ?, ?, ?, ?, 'active')`;
         db.run(insertSql, [
             id,
             key,
@@ -2396,6 +2450,7 @@ export async function storeEntry(options) {
             embeddingModel,
             tags.length > 0 ? JSON.stringify(tags) : null,
             '{}',
+            persistedProvenance,
             now,
             now,
             ttl ? now + (ttl * 1000) : null
@@ -2433,6 +2488,17 @@ export async function storeEntry(options) {
  * Uses HNSW index for 150x faster search when available
  */
 export async function searchEntries(options) {
+    if (options.provenanceFilter?.length) {
+        const invalid = options.provenanceFilter.filter(p => !isValidProvenanceType(p));
+        if (invalid.length > 0) {
+            return {
+                success: false,
+                results: [],
+                searchTime: 0,
+                error: `Invalid provenance filter value(s): ${invalid.join(', ')} — must be one of: ${PROVENANCE_TYPES.join(', ')}`,
+            };
+        }
+    }
     // ADR-053: Try AgentDB v3 bridge first
     const bridge = await getBridge();
     if (bridge) {
@@ -2441,7 +2507,7 @@ export async function searchEntries(options) {
             return bridgeResult;
     }
     // Fallback: raw sql.js
-    const { query, namespace, limit = 10, threshold = 0.3, dbPath: customPath } = options;
+    const { query, namespace, limit = 10, threshold = 0.3, dbPath: customPath, provenanceFilter } = options;
     const effectiveNamespace = namespace || 'all';
     const swarmDir = getMemoryRoot();
     const dbPath = customPath ? path.resolve(customPath) : path.join(swarmDir, 'memory.db');
@@ -2467,10 +2533,18 @@ export async function searchEntries(options) {
                 const db = new SQL.Database(fileBuffer);
                 const reranked = [];
                 for (const candidate of rabitqCandidates) {
-                    const stmt = db.prepare('SELECT content, embedding FROM memory_entries WHERE id = ? AND status = ?');
+                    // ADR-323: provenance_type is fetched in the same per-candidate
+                    // query (no extra round-trip) so a provenance-filtered search
+                    // still gets RaBitQ's speedup instead of falling back to brute
+                    // force.
+                    const stmt = db.prepare('SELECT content, embedding, provenance_type FROM memory_entries WHERE id = ? AND status = ?');
                     stmt.bind([candidate.id, 'active']);
                     if (stmt.step()) {
-                        const [content, embeddingJson] = stmt.get();
+                        const [content, embeddingJson, provenanceTypeVal] = stmt.get();
+                        if (provenanceFilter?.length && !provenanceFilter.includes(provenanceTypeVal || 'unknown')) {
+                            stmt.free();
+                            continue;
+                        }
                         let score = 0;
                         if (embeddingJson) {
                             try {
@@ -2486,13 +2560,17 @@ export async function searchEntries(options) {
                                 content: (content || '').substring(0, 60) + ((content || '').length > 60 ? '...' : ''),
                                 score,
                                 namespace: candidate.namespace,
+                                provenanceType: provenanceTypeVal || 'unknown',
                             });
                         }
                     }
                     stmt.free();
                 }
                 db.close();
-                if (reranked.length > 0) {
+                // A filtered ANN candidate window can underfill even when qualifying
+                // rows exist outside that window. Fall through to the authoritative
+                // filtered SQL scan unless ANN filled the requested page.
+                if (reranked.length > 0 && (!provenanceFilter?.length || reranked.length >= limit)) {
                     reranked.sort((a, b) => b.score - a.score);
                     return { success: true, results: reranked.slice(0, limit), searchTime: Date.now() - startTime };
                 }
@@ -2500,15 +2578,56 @@ export async function searchEntries(options) {
         }
         catch { /* RaBitQ unavailable, fall through */ }
         // Try HNSW search (150x faster than brute-force)
-        const hnswResults = await searchHNSWIndex(queryEmbedding, { k: limit, namespace: effectiveNamespace });
+        const hnswResults = await searchHNSWIndex(queryEmbedding, {
+            k: provenanceFilter?.length ? Math.max(limit * 4, limit + 32) : limit,
+            namespace: effectiveNamespace,
+        });
         if (hnswResults && hnswResults.length > 0) {
             // Filter by threshold
-            const filtered = hnswResults.filter(r => r.score >= threshold);
-            return {
-                success: true,
-                results: filtered,
-                searchTime: Date.now() - startTime
-            };
+            let filtered = hnswResults.filter(r => r.score >= threshold);
+            // ADR-323: the in-memory HNSW index doesn't carry provenance_type on
+            // its entries, so resolve it from SQLite for a consistent result shape
+            // and apply any trust filter before returning.
+            if (filtered.length > 0) {
+                try {
+                    const initSqlJs = (await import('sql.js')).default;
+                    const SQL = await initSqlJs();
+                    const fileBuffer = readFileMaybeEncrypted(dbPath, null);
+                    const db = new SQL.Database(fileBuffer);
+                    const provenanceByKey = new Map();
+                    for (const r of filtered) {
+                        const stmt = db.prepare('SELECT provenance_type FROM memory_entries WHERE namespace = ? AND key = ? LIMIT 1');
+                        stmt.bind([r.namespace, r.key]);
+                        if (stmt.step()) {
+                            provenanceByKey.set(`${r.namespace}::${r.key}`, stmt.get()[0] || 'unknown');
+                        }
+                        stmt.free();
+                    }
+                    db.close();
+                    filtered = filtered
+                        .map(r => ({ ...r, provenanceType: provenanceByKey.get(`${r.namespace}::${r.key}`) || 'unknown' }));
+                    if (provenanceFilter?.length) {
+                        filtered = filtered.filter(r => provenanceFilter.includes(r.provenanceType));
+                    }
+                }
+                catch {
+                    // A requested trust filter fails closed. Unfiltered callers retain
+                    // backward-compatible results with an explicit unknown label.
+                    filtered = provenanceFilter?.length
+                        ? []
+                        : filtered.map(r => ({ ...r, provenanceType: 'unknown' }));
+                }
+            }
+            if (!provenanceFilter?.length || filtered.length >= limit) {
+                return {
+                    success: true,
+                    results: filtered.slice(0, limit),
+                    searchTime: Date.now() - startTime
+                };
+            }
+            // The ANN window did not contain enough matching provenance rows.
+            // Continue into the filtered SQL path to avoid false-empty/underfilled
+            // results caused by post-filtering only the unfiltered top-k.
         }
         // Fall back to brute-force SQLite search
         const initSqlJs = (await import('sql.js')).default;
@@ -2516,11 +2635,21 @@ export async function searchEntries(options) {
         const fileBuffer = readFileMaybeEncrypted(dbPath, null);
         const db = new SQL.Database(fileBuffer);
         // Get entries with embeddings
-        const searchStmt = db.prepare(effectiveNamespace !== 'all'
-            ? `SELECT id, key, namespace, content, embedding FROM memory_entries WHERE status = 'active' AND namespace = ? LIMIT 1000`
-            : `SELECT id, key, namespace, content, embedding FROM memory_entries WHERE status = 'active' LIMIT 1000`);
+        // ADR-323: build the WHERE clause incrementally so namespace and
+        // provenance filters compose (both, either, or neither).
+        const whereClauses = [`status = 'active'`];
+        const whereParams = [];
         if (effectiveNamespace !== 'all') {
-            searchStmt.bind([effectiveNamespace]);
+            whereClauses.push('namespace = ?');
+            whereParams.push(effectiveNamespace);
+        }
+        if (provenanceFilter?.length) {
+            whereClauses.push(`provenance_type IN (${provenanceFilter.map(() => '?').join(',')})`);
+            whereParams.push(...provenanceFilter);
+        }
+        const searchStmt = db.prepare(`SELECT id, key, namespace, content, embedding, provenance_type FROM memory_entries WHERE ${whereClauses.join(' AND ')} LIMIT 1000`);
+        if (whereParams.length > 0) {
+            searchStmt.bind(whereParams);
         }
         const searchRows = [];
         while (searchStmt.step()) {
@@ -2531,7 +2660,7 @@ export async function searchEntries(options) {
         const results = [];
         if (entries[0]?.values) {
             for (const row of entries[0].values) {
-                const [id, key, ns, content, embeddingJson] = row;
+                const [id, key, ns, content, embeddingJson, provenanceTypeVal] = row;
                 let score = 0;
                 if (embeddingJson) {
                     try {
@@ -2557,7 +2686,8 @@ export async function searchEntries(options) {
                         key: key || id.substring(0, 15),
                         content: (content || '').substring(0, 60) + ((content || '').length > 60 ? '...' : ''),
                         score,
-                        namespace: ns || 'default'
+                        namespace: ns || 'default',
+                        provenanceType: provenanceTypeVal || 'unknown',
                     });
                 }
             }
@@ -2605,6 +2735,17 @@ function cosineSim(a, b) {
  * List all entries from the memory database
  */
 export async function listEntries(options) {
+    if (options.provenanceFilter?.length) {
+        const invalid = options.provenanceFilter.filter(p => !isValidProvenanceType(p));
+        if (invalid.length > 0) {
+            return {
+                success: false,
+                entries: [],
+                total: 0,
+                error: `Invalid provenance filter value(s): ${invalid.join(', ')} — must be one of: ${PROVENANCE_TYPES.join(', ')}`,
+            };
+        }
+    }
     // ADR-053: Try AgentDB v3 bridge first
     const bridge = await getBridge();
     if (bridge) {
@@ -2613,7 +2754,7 @@ export async function listEntries(options) {
             return bridgeResult;
     }
     // Fallback: raw sql.js
-    const { namespace, limit = 20, offset = 0, dbPath: customPath } = options;
+    const { namespace, limit = 20, offset = 0, dbPath: customPath, provenanceFilter } = options;
     const swarmDir = getMemoryRoot();
     const dbPath = customPath || path.join(swarmDir, 'memory.db');
     try {
@@ -2630,12 +2771,20 @@ export async function listEntries(options) {
         // that predate the status column may have NULL after migration.
         // See memory-bridge.ts:bridgeListEntries for full context.
         // Get total count
-        const countStmt = namespace
-            ? db.prepare(`SELECT COUNT(*) as cnt FROM memory_entries WHERE (status = 'active' OR status IS NULL) AND namespace = ?`)
-            : db.prepare(`SELECT COUNT(*) as cnt FROM memory_entries WHERE (status = 'active' OR status IS NULL)`);
+        const whereClauses = [`(status = 'active' OR status IS NULL)`];
+        const whereParams = [];
         if (namespace) {
-            countStmt.bind([namespace]);
+            whereClauses.push('namespace = ?');
+            whereParams.push(namespace);
+        }
+        if (provenanceFilter?.length) {
+            whereClauses.push(`provenance_type IN (${provenanceFilter.map(() => '?').join(',')})`);
+            whereParams.push(...provenanceFilter);
         }
+        const whereSql = whereClauses.join(' AND ');
+        const countStmt = db.prepare(`SELECT COUNT(*) as cnt FROM memory_entries WHERE ${whereSql}`);
+        if (whereParams.length > 0)
+            countStmt.bind(whereParams);
         const countRows = [];
         while (countStmt.step()) {
             countRows.push(countStmt.get());
@@ -2647,15 +2796,10 @@ export async function listEntries(options) {
         const safeLimit = parseInt(String(limit), 10) || 100;
         const safeOffset = parseInt(String(offset), 10) || 0;
         // #2120 — same NULL-as-active acceptance as the count above.
-        const listStmt = namespace
-            ? db.prepare(`SELECT id, key, namespace, content, embedding, access_count, created_at, updated_at FROM memory_entries WHERE (status = 'active' OR status IS NULL) AND namespace = ? ORDER BY updated_at DESC LIMIT ? OFFSET ?`)
-            : db.prepare(`SELECT id, key, namespace, content, embedding, access_count, created_at, updated_at FROM memory_entries WHERE (status = 'active' OR status IS NULL) ORDER BY updated_at DESC LIMIT ? OFFSET ?`);
-        if (namespace) {
-            listStmt.bind([namespace, safeLimit, safeOffset]);
-        }
-        else {
-            listStmt.bind([safeLimit, safeOffset]);
-        }
+        const listStmt = db.prepare(`SELECT id, key, namespace, content, embedding, access_count, created_at, updated_at, provenance_type
+       FROM memory_entries WHERE ${whereSql}
+       ORDER BY updated_at DESC LIMIT ? OFFSET ?`);
+        listStmt.bind([...whereParams, safeLimit, safeOffset]);
         const listRows = [];
         while (listStmt.step()) {
             listRows.push(listStmt.get());
@@ -2665,7 +2809,7 @@ export async function listEntries(options) {
         const entries = [];
         if (result[0]?.values) {
             for (const row of result[0].values) {
-                const [id, key, ns, content, embedding, accessCount, createdAt, updatedAt] = row;
+                const [id, key, ns, content, embedding, accessCount, createdAt, updatedAt, provenanceTypeVal] = row;
                 const entry = {
                     // #2073: don't truncate id when content is requested — callers
                     // (notably memory_export) need the full id to round-trip via import.
@@ -2676,7 +2820,8 @@ export async function listEntries(options) {
                     accessCount: accessCount || 0,
                     createdAt: createdAt || new Date().toISOString(),
                     updatedAt: updatedAt || new Date().toISOString(),
-                    hasEmbedding: !!embedding && embedding.length > 10
+                    hasEmbedding: !!embedding && embedding.length > 10,
+                    provenanceType: provenanceTypeVal || 'unknown'
                 };
                 if (options.includeContent) {
                     entry.content = content || '';

package/dist/src/services/bounded-worker-pool.d.ts

@@ -0,0 +1,28 @@
+export interface BoundedTask<T> {
+    id: string;
+    run: (signal: AbortSignal) => Promise<T>;
+}
+export interface BoundedTaskResult<T> {
+    id: string;
+    status: 'fulfilled' | 'rejected' | 'cancelled';
+    value?: T;
+    error?: string;
+}
+export interface BoundedPoolResult<T> {
+    results: BoundedTaskResult<T>[];
+    peakConcurrency: number;
+    durationMs: number;
+}
+/**
+ * Deterministic bounded worker pool for Codex/MetaHarness fanout.
+ *
+ * Completion order never affects result order. The caller-supplied AbortSignal
+ * and timeout cancel both queued and cooperative running work. No unbounded
+ * Promise.all is used.
+ */
+export declare function runBoundedPool<T>(tasks: readonly BoundedTask<T>[], options: {
+    maxConcurrency: number;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}): Promise<BoundedPoolResult<T>>;
+//# sourceMappingURL=bounded-worker-pool.d.ts.map

package/dist/src/services/bounded-worker-pool.js

@@ -0,0 +1,90 @@
+/**
+ * Deterministic bounded worker pool for Codex/MetaHarness fanout.
+ *
+ * Completion order never affects result order. The caller-supplied AbortSignal
+ * and timeout cancel both queued and cooperative running work. No unbounded
+ * Promise.all is used.
+ */
+export async function runBoundedPool(tasks, options) {
+    const started = Date.now();
+    if (!Number.isInteger(options.maxConcurrency) || options.maxConcurrency < 1) {
+        throw new Error('maxConcurrency must be a positive integer');
+    }
+    const ids = new Set();
+    for (const task of tasks) {
+        if (!task.id || ids.has(task.id))
+            throw new Error(`duplicate or empty task id: ${task.id}`);
+        ids.add(task.id);
+    }
+    const maxConcurrency = Math.min(options.maxConcurrency, tasks.length || 1);
+    const controller = new AbortController();
+    const onAbort = () => controller.abort(options.signal?.reason ?? new Error('cancelled'));
+    options.signal?.addEventListener('abort', onAbort, { once: true });
+    const timer = options.timeoutMs && options.timeoutMs > 0
+        ? setTimeout(() => controller.abort(new Error('worker-pool-timeout')), options.timeoutMs)
+        : undefined;
+    const results = new Map();
+    let cursor = 0;
+    let active = 0;
+    let peakConcurrency = 0;
+    const worker = async () => {
+        while (cursor < tasks.length) {
+            const taskIndex = cursor++;
+            const task = tasks[taskIndex];
+            if (controller.signal.aborted) {
+                results.set(task.id, { id: task.id, status: 'cancelled', error: String(controller.signal.reason ?? 'cancelled') });
+                continue;
+            }
+            active += 1;
+            peakConcurrency = Math.max(peakConcurrency, active);
+            let rejectOnAbort;
+            try {
+                const abort = new Promise((_, reject) => {
+                    if (controller.signal.aborted) {
+                        reject(controller.signal.reason ?? new Error('cancelled'));
+                        return;
+                    }
+                    rejectOnAbort = () => reject(controller.signal.reason ?? new Error('cancelled'));
+                    controller.signal.addEventListener('abort', rejectOnAbort, { once: true });
+                });
+                // Promise.race enforces the caller-visible wall time even when a
+                // third-party task ignores AbortSignal. Cooperative tasks should still
+                // stop their underlying work when the signal fires.
+                const value = await Promise.race([task.run(controller.signal), abort]);
+                results.set(task.id, controller.signal.aborted
+                    ? { id: task.id, status: 'cancelled', error: String(controller.signal.reason ?? 'cancelled') }
+                    : { id: task.id, status: 'fulfilled', value });
+            }
+            catch (error) {
+                results.set(task.id, {
+                    id: task.id,
+                    status: controller.signal.aborted ? 'cancelled' : 'rejected',
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+            finally {
+                if (rejectOnAbort)
+                    controller.signal.removeEventListener('abort', rejectOnAbort);
+                active -= 1;
+            }
+        }
+    };
+    try {
+        await Promise.all(Array.from({ length: maxConcurrency }, () => worker()));
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+        options.signal?.removeEventListener('abort', onAbort);
+    }
+    return {
+        results: tasks.map((task) => results.get(task.id) ?? {
+            id: task.id,
+            status: 'cancelled',
+            error: 'not-started',
+        }),
+        peakConcurrency,
+        durationMs: Date.now() - started,
+    };
+}
+//# sourceMappingURL=bounded-worker-pool.js.map