limen-ai 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -5,6 +5,35 @@ All notable changes to Limen are documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.3.0] - 2026-03-31
+
+### Added
+- **Convenience API** (`remember`, `recall`, `forget`, `connect`, `reflect`, `promptInstructions`) — the thesis becomes accessible. 3 lines to store a belief. Full engineering controls: Design Source, Breaker pass, Certifier gate.
+- **FTS5 Full-Text Search** (`search`) — find beliefs by content. Primary index (`unicode61` tokenizer) for Latin/Cyrillic, secondary index (`trigram`) for CJK and substring matching. External content mode (zero data duplication). Tenant-scoped. FTS5 query injection sanitized.
+- **Cognitive Metabolism** — beliefs that breathe. FSRS power-decay formula `R(t) = (1 + t/(9*S))^(-1)` computed on every read, never stored. `effective_confidence` returned alongside raw `confidence`. Freshness classification (Fresh/Aging/Stale). Access tracking with batched flush. `minConfidence` filters by decayed confidence.
+- **Wrongness containment** — `maxAutoConfidence` ceiling (default 0.7) prevents confidence laundering. Auto-extracted claims cannot start above 0.7 unless human-verified via `evidence_path` grounding.
+- **Stability per claim** — predicate-based stability assignment: governance 365d, architectural 180d, finding 90d, warning 30d, ephemeral 7d, preference 120d. Configurable patterns.
+- `retractClaim` on `ClaimApi` — programmatic claim retraction with audit trail.
+- `searchClaims` on `ClaimApi` — programmatic FTS5 search with BM25 ranking.
+- Migrations v37 (FTS5 primary + triggers), v38 (FTS5 CJK trigram + triggers), v39 (cognitive metabolism columns).
+- 235 new tests (3,188 → 3,423). Every test through A21 dual-path (success + rejection).
+
+### Changed
+- npm description updated to "Governed knowledge engine for AI agents."
+- npm keywords expanded for discoverability.
+- `BeliefView` extended with `effectiveConfidence`, `freshness`, `stability`, `lastAccessedAt`, `accessCount`.
+- `SearchResult.score` now uses `effectiveConfidence * BM25` — old claims rank lower than fresh ones.
+- `recall()` and `search()` return decay-aware results by default.
+
+### Removed
+- **Knowledge API stub** (`KnowledgeApi`, `KnowledgeApiImpl`, MCP knowledge tools) — dead code that returned `{ memoriesCreated: 0 }`. Replaced by the convenience API built through full engineering controls.
+
+## [1.2.0] - 2026-03-28
+
+### Added
+- `setDefaultAgent` API for library-mode agent identity.
+- MCP server: session adapter with knowledge tools (subsequently removed in v1.3.0).
+
 ## [1.1.0] - 2026-03-24
 
 ### Added

package/dist/api/convenience/convenience_init.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Phase 1: Convenience API eager initialization.
+ *
+ * Registers the "limen-convenience" agent and creates the convenience mission
+ * during createLimen(). This provides the missionId and taskId needed for
+ * all convenience API claim operations.
+ *
+ * Design Source: Decision 1 (MissionId for Convenience Claims)
+ * Invariants: I-CONV-01 (immediately usable), I-CONV-02 (created once, cached)
+ *
+ * Trade-off: Adds ~30ms to createLimen() (already async). All convenience
+ * methods are synchronous Result<T> after engine creation.
+ */
+import type { AgentId, MissionId, TaskId } from '../../kernel/interfaces/index.js';
+import type { TimeProvider } from '../../kernel/interfaces/time.js';
+import type { AgentApi, MissionApi } from '../interfaces/api.js';
+/**
+ * Result of convenience initialization.
+ * Contains the cached IDs needed for all convenience operations.
+ */
+export interface ConvenienceInitResult {
+    readonly agentId: AgentId;
+    readonly missionId: MissionId;
+    readonly taskId: TaskId | null;
+}
+/** Well-known agent name for convenience API */
+export declare const CONVENIENCE_AGENT_NAME = "limen-convenience";
+/** Well-known mission objective for convenience API */
+export declare const CONVENIENCE_MISSION_OBJECTIVE = "limen-convenience-api";
+/**
+ * Initialize the convenience API infrastructure.
+ *
+ * 1. Register (or retrieve) the "limen-convenience" agent
+ * 2. Create the convenience mission with standard config
+ * 3. Propose a task graph with a single task
+ * 4. Return cached IDs for all subsequent operations
+ *
+ * This runs during createLimen() (already async). All failures
+ * propagate as exceptions to the createLimen() caller.
+ *
+ * @param agents - The AgentApi for agent registration
+ * @param missions - The MissionApi for mission creation
+ * @param setDefaultAgent - Function to set the default agent identity
+ */
+export declare function initializeConvenience(agents: AgentApi, missions: MissionApi, setDefaultAgent: (agentId: AgentId) => void, time: TimeProvider): Promise<ConvenienceInitResult>;
+//# sourceMappingURL=convenience_init.d.ts.map

package/dist/api/convenience/convenience_init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"convenience_init.d.ts","sourceRoot":"","sources":["../../../src/api/convenience/convenience_init.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,kCAAkC,CAAC;AACnF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AACpE,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAEjE;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED,gDAAgD;AAChD,eAAO,MAAM,sBAAsB,sBAAsB,CAAC;AAE1D,uDAAuD;AACvD,eAAO,MAAM,6BAA6B,0BAA0B,CAAC;AAErE;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,QAAQ,EAChB,QAAQ,EAAE,UAAU,EACpB,eAAe,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,EAC3C,IAAI,EAAE,YAAY,GACjB,OAAO,CAAC,qBAAqB,CAAC,CAkFhC"}

package/dist/api/convenience/convenience_init.js

@@ -0,0 +1,111 @@
+/**
+ * Phase 1: Convenience API eager initialization.
+ *
+ * Registers the "limen-convenience" agent and creates the convenience mission
+ * during createLimen(). This provides the missionId and taskId needed for
+ * all convenience API claim operations.
+ *
+ * Design Source: Decision 1 (MissionId for Convenience Claims)
+ * Invariants: I-CONV-01 (immediately usable), I-CONV-02 (created once, cached)
+ *
+ * Trade-off: Adds ~30ms to createLimen() (already async). All convenience
+ * methods are synchronous Result<T> after engine creation.
+ */
+/** Well-known agent name for convenience API */
+export const CONVENIENCE_AGENT_NAME = 'limen-convenience';
+/** Well-known mission objective for convenience API */
+export const CONVENIENCE_MISSION_OBJECTIVE = 'limen-convenience-api';
+/**
+ * Initialize the convenience API infrastructure.
+ *
+ * 1. Register (or retrieve) the "limen-convenience" agent
+ * 2. Create the convenience mission with standard config
+ * 3. Propose a task graph with a single task
+ * 4. Return cached IDs for all subsequent operations
+ *
+ * This runs during createLimen() (already async). All failures
+ * propagate as exceptions to the createLimen() caller.
+ *
+ * @param agents - The AgentApi for agent registration
+ * @param missions - The MissionApi for mission creation
+ * @param setDefaultAgent - Function to set the default agent identity
+ */
+export async function initializeConvenience(agents, missions, setDefaultAgent, time) {
+    // 1. Register agent (idempotent -- if already exists, retrieve it)
+    let agentId;
+    try {
+        const agent = await agents.register({
+            name: CONVENIENCE_AGENT_NAME,
+            domains: ['convenience'],
+            capabilities: ['remember', 'recall', 'forget', 'connect', 'reflect'],
+        });
+        agentId = agent.id;
+    }
+    catch (regErr) {
+        // Agent may already exist from a previous createLimen() with the same dataDir.
+        // Try to retrieve it instead.
+        const existing = await agents.get(CONVENIENCE_AGENT_NAME);
+        if (existing) {
+            agentId = existing.id;
+        }
+        else {
+            throw regErr;
+        }
+    }
+    // 2. Set default agent so all ClaimApi calls carry this agentId
+    setDefaultAgent(agentId);
+    // 3. Create convenience mission
+    // Deadline: 1 year from now. Budget: 1,000,000 tokens.
+    const deadline = new Date(time.nowMs() + 365 * 24 * 60 * 60 * 1000).toISOString();
+    const missionHandle = await missions.create({
+        agent: CONVENIENCE_AGENT_NAME,
+        objective: CONVENIENCE_MISSION_OBJECTIVE,
+        constraints: {
+            tokenBudget: 1_000_000,
+            deadline,
+        },
+    });
+    const missionId = missionHandle.id;
+    // 4. Propose a task graph with a single convenience task
+    await missionHandle.proposeTaskGraph({
+        missionId,
+        tasks: [{
+                id: 'convenience-task',
+                description: 'Convenience API operations',
+                executionMode: 'deterministic',
+                estimatedTokens: 1_000_000,
+            }],
+        dependencies: [],
+        objectiveAlignment: 'Convenience API thin delegation layer for remember/recall/forget/connect/reflect',
+    });
+    // 5. Get the task ID from the graph
+    // The task graph creates tasks with IDs that are mission-scoped.
+    // We need to query the mission's tasks to find the one we created.
+    // The task ID format is typically the mission's task graph ID.
+    // For simplicity, we look up the mission to get the task.
+    const missionState = await missions.get(missionId);
+    if (!missionState) {
+        throw new Error(`Convenience mission ${missionId} not found after creation`);
+    }
+    // Propose task execution to get the actual taskId
+    // The taskId from the graph is a string, but we need the internal TaskId.
+    // We'll use the graph's task count to derive it.
+    // Actually, looking at the orchestration, tasks are created by proposeTaskGraph
+    // and their IDs are returned. But proposeTaskGraph returns TaskGraphOutput
+    // which has taskCount but not individual task IDs.
+    //
+    // For the convenience API, the missionId is the critical piece.
+    // The taskId can be null for convenience claims. Let me verify...
+    // Looking at ClaimCreateInput: taskId is TaskId | null.
+    // MissionId is required (not null). TaskId can be null.
+    //
+    // Decision: Use null for taskId. The missionId is sufficient for
+    // SC-11 validation. This avoids the complexity of retrieving the
+    // internal TaskId from the task graph.
+    return {
+        agentId,
+        missionId,
+        taskId: null,
+    };
+}
+//# sourceMappingURL=convenience_init.js.map

package/dist/api/convenience/convenience_init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"convenience_init.js","sourceRoot":"","sources":["../../../src/api/convenience/convenience_init.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAgBH,gDAAgD;AAChD,MAAM,CAAC,MAAM,sBAAsB,GAAG,mBAAmB,CAAC;AAE1D,uDAAuD;AACvD,MAAM,CAAC,MAAM,6BAA6B,GAAG,uBAAuB,CAAC;AAErE;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,MAAgB,EAChB,QAAoB,EACpB,eAA2C,EAC3C,IAAkB;IAElB,mEAAmE;IACnE,IAAI,OAAgB,CAAC;IACrB,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC;YAClC,IAAI,EAAE,sBAAsB;YAC5B,OAAO,EAAE,CAAC,aAAa,CAAC;YACxB,YAAY,EAAE,CAAC,UAAU,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,SAAS,CAAC;SACrE,CAAC,CAAC;QACH,OAAO,GAAG,KAAK,CAAC,EAAE,CAAC;IACrB,CAAC;IAAC,OAAO,MAAe,EAAE,CAAC;QACzB,+EAA+E;QAC/E,8BAA8B;QAC9B,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,GAAG,CAAC,sBAAsB,CAAC,CAAC;QAC1D,IAAI,QAAQ,EAAE,CAAC;YACb,OAAO,GAAG,QAAQ,CAAC,EAAE,CAAC;QACxB,CAAC;aAAM,CAAC;YACN,MAAM,MAAM,CAAC;QACf,CAAC;IACH,CAAC;IAED,gEAAgE;IAChE,eAAe,CAAC,OAAO,CAAC,CAAC;IAEzB,gCAAgC;IAChC,uDAAuD;IACvD,MAAM,QAAQ,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,GAAG,GAAG,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC;IAClF,MAAM,aAAa,GAAG,MAAM,QAAQ,CAAC,MAAM,CAAC;QAC1C,KAAK,EAAE,sBAAsB;QAC7B,SAAS,EAAE,6BAA6B;QACxC,WAAW,EAAE;YACX,WAAW,EAAE,SAAS;YACtB,QAAQ;SACT;KACF,CAAC,CAAC;IAEH,MAAM,SAAS,GAAG,aAAa,CAAC,EAAE,CAAC;IAEnC,yDAAyD;IACzD,MAAM,aAAa,CAAC,gBAAgB,CAAC;QACnC,SAAS;QACT,KAAK,EAAE,CAAC;gBACN,EAAE,EAAE,kBAAkB;gBACtB,WAAW,EAAE,4BAA4B;gBACzC,aAAa,EAAE,eAAe;gBAC9B,eAAe,EAAE,SAAS;aAC3B,CAAC;QACF,YAAY,EAAE,EAAE;QAChB,kBAAkB,EAAE,kFAAkF;KACvG,CAAC,CAAC;IAEH,oCAAoC;IACpC,iEAAiE;IACjE,mEAAmE;IACnE,+DAA+D;IAC/D,0DAA0D;IAC1D,MAAM,YAAY,GAAG,MAAM,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACnD,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,MAAM,IAAI,KAAK,CAAC,uBAAuB,SAAS,2BAA2B,CAAC,CAAC;IAC/E,CAAC;IAED,kDAAkD;IAClD,0EAA0E;IAC1E,iDAAiD;IACjD,gFAAgF;IAChF,2EAA2E;IAC3E,mDAAmD;IACnD,EAAE;IACF,gEAAgE;IAChE,kEAAkE;IAClE,wDAAwD;IACxD,wDAAwD;IACxD,EAAE;IACF,iEAAiE;IACjE,iEAAiE;IACjE,uCAAuC;IAEvC,OAAO;QACL,OAAO;QACP,SAAS;QACT,MAAM,EAAE,IAAI;KACb,CAAC;AACJ,CAAC"}

package/dist/api/convenience/convenience_layer.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Phase 1 Convenience API Implementation.
+ *
+ * Thin delegation layer that translates cognitive operations (remember, recall,
+ * forget, connect, reflect) into ClaimApi system calls. No new system calls.
+ * No new database tables. No new schema.
+ *
+ * Design Source: docs/sprints/PHASE-1-DESIGN-SOURCE.md
+ * Invariants: I-CONV-01 through I-CONV-18
+ *
+ * Architecture: This is the "store" layer in the three-file pattern.
+ * convenience_types.ts (contract) -> convenience_layer.ts (implementation)
+ *
+ * Governance boundary (I-17): Only imports ClaimApi, never ClaimSystem/ClaimStore.
+ */
+import type { Result } from '../../kernel/interfaces/index.js';
+import type { MissionId, TaskId } from '../../kernel/interfaces/index.js';
+import type { DatabaseConnection } from '../../kernel/interfaces/database.js';
+import type { TimeProvider } from '../../kernel/interfaces/time.js';
+import type { ClaimApi } from '../interfaces/api.js';
+import type { RememberOptions, RememberResult, RecallOptions, BeliefView, ReflectEntry, ReflectResult, SearchOptions, SearchResult } from './convenience_types.js';
+/**
+ * Dependencies for the convenience layer.
+ * Injected during createLimen() -- no direct access to internals.
+ */
+export interface ConvenienceLayerDeps {
+    readonly claims: ClaimApi;
+    readonly getConnection: () => DatabaseConnection;
+    readonly time: TimeProvider;
+    readonly missionId: MissionId;
+    readonly taskId: TaskId | null;
+    readonly maxAutoConfidence: number;
+}
+/**
+ * The convenience layer interface -- methods added to the Limen object.
+ */
+export interface ConvenienceLayer {
+    remember(subject: string, predicate: string, value: string, options?: RememberOptions): Result<RememberResult>;
+    remember(text: string, options?: RememberOptions): Result<RememberResult>;
+    remember(subjectOrText: string, predicateOrOptions?: string | RememberOptions, value?: string, options?: RememberOptions): Result<RememberResult>;
+    recall(subject?: string, predicate?: string, options?: RecallOptions): Result<readonly BeliefView[]>;
+    forget(claimId: string, reason?: string): Result<void>;
+    connect(claimId1: string, claimId2: string, type: 'supports' | 'contradicts' | 'supersedes' | 'derived_from'): Result<void>;
+    reflect(entries: readonly ReflectEntry[]): Result<ReflectResult>;
+    promptInstructions(): string;
+    /** Phase 2 §2.4: Full-text search across claim content. */
+    search(query: string, options?: SearchOptions): Result<readonly SearchResult[]>;
+}
+/**
+ * Create the convenience layer.
+ *
+ * Returns an object with all convenience methods, ready to be spread
+ * onto the Limen engine object.
+ *
+ * All methods are synchronous Result<T> (I-CONV-01: immediately usable).
+ * Closure captures deps -- survives Object.freeze (I-CONV-15).
+ */
+export declare function createConvenienceLayer(deps: ConvenienceLayerDeps): ConvenienceLayer;
+//# sourceMappingURL=convenience_layer.d.ts.map

package/dist/api/convenience/convenience_layer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"convenience_layer.d.ts","sourceRoot":"","sources":["../../../src/api/convenience/convenience_layer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kCAAkC,CAAC;AAC/D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,kCAAkC,CAAC;AAC1E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qCAAqC,CAAC;AAC9E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AASpE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAErD,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EACd,aAAa,EACb,UAAU,EACV,YAAY,EACZ,aAAa,EACb,aAAa,EACb,YAAY,EACb,MAAM,wBAAwB,CAAC;AAuChC;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC1B,QAAQ,CAAC,aAAa,EAAE,MAAM,kBAAkB,CAAC;IACjD,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,MAAM,CAAC,cAAc,CAAC,CAAC;IAC/G,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,MAAM,CAAC,cAAc,CAAC,CAAC;IAC1E,QAAQ,CAAC,aAAa,EAAE,MAAM,EAAE,kBAAkB,CAAC,EAAE,MAAM,GAAG,eAAe,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,MAAM,CAAC,cAAc,CAAC,CAAC;IAClJ,MAAM,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,MAAM,CAAC,SAAS,UAAU,EAAE,CAAC,CAAC;IACrG,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;IACvD,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,aAAa,GAAG,YAAY,GAAG,cAAc,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;IAC5H,OAAO,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,GAAG,MAAM,CAAC,aAAa,CAAC,CAAC;IACjE,kBAAkB,IAAI,MAAM,CAAC;IAC7B,2DAA2D;IAC3D,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,MAAM,CAAC,SAAS,YAAY,EAAE,CAAC,CAAC;CACjF;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,oBAAoB,GAAG,gBAAgB,CAqYnF"}

package/dist/api/convenience/convenience_layer.js

@@ -0,0 +1,373 @@
+/**
+ * Phase 1 Convenience API Implementation.
+ *
+ * Thin delegation layer that translates cognitive operations (remember, recall,
+ * forget, connect, reflect) into ClaimApi system calls. No new system calls.
+ * No new database tables. No new schema.
+ *
+ * Design Source: docs/sprints/PHASE-1-DESIGN-SOURCE.md
+ * Invariants: I-CONV-01 through I-CONV-18
+ *
+ * Architecture: This is the "store" layer in the three-file pattern.
+ * convenience_types.ts (contract) -> convenience_layer.ts (implementation)
+ *
+ * Governance boundary (I-17): Only imports ClaimApi, never ClaimSystem/ClaimStore.
+ */
+import { createHash } from 'node:crypto';
+import { VALID_RELATIONSHIP_TYPES, VALID_CATEGORIES, MAX_STATEMENT_LENGTH, MAX_REFLECT_ENTRIES, DEFAULT_RECALL_LIMIT, DEFAULT_SEARCH_LIMIT, MAX_SEARCH_LIMIT, } from './convenience_types.js';
+import { generatePromptInstructions } from './convenience_prompt.js';
+// ── Result Helpers ──
+function ok(value) {
+    return { ok: true, value };
+}
+function err(code, message) {
+    return { ok: false, error: { code, message, spec: 'Phase-1' } };
+}
+// ── SHA-256 Subject Generation ──
+/**
+ * Generate a subject URN from text content using SHA-256.
+ * Format: entity:observation:<sha256-hex-first-12>
+ *
+ * I-CONV-13: Satisfies CCP subject validation (3 colon-separated segments).
+ */
+function hashSubject(text) {
+    const hash = createHash('sha256').update(text, 'utf8').digest('hex');
+    return `entity:observation:${hash.substring(0, 12)}`;
+}
+/**
+ * Create the convenience layer.
+ *
+ * Returns an object with all convenience methods, ready to be spread
+ * onto the Limen engine object.
+ *
+ * All methods are synchronous Result<T> (I-CONV-01: immediately usable).
+ * Closure captures deps -- survives Object.freeze (I-CONV-15).
+ */
+export function createConvenienceLayer(deps) {
+    const { claims, getConnection, time, missionId, taskId, maxAutoConfidence } = deps;
+    /**
+     * Compute effective confidence, applying the maxAutoConfidence cap
+     * unless evidence_path grounding with non-empty evidenceRefs is provided.
+     *
+     * I-CONV-04 (CONSTITUTIONAL): Cap enforcement.
+     * I-CONV-05 (CONSTITUTIONAL): Bypass with evidence.
+     */
+    function effectiveConfidence(requestedConfidence, groundingMode, evidenceRefs) {
+        const confidence = requestedConfidence ?? maxAutoConfidence;
+        // Bypass: evidence_path with non-empty evidenceRefs
+        if (groundingMode === 'evidence_path' && evidenceRefs && evidenceRefs.length > 0) {
+            return confidence;
+        }
+        // Cap at maxAutoConfidence
+        return Math.min(confidence, maxAutoConfidence);
+    }
+    /**
+     * 3-param remember: explicit subject, predicate, value.
+     */
+    function remember3(subject, predicate, value, options) {
+        // Validate confidence if provided
+        if (options?.confidence !== undefined) {
+            if (!Number.isFinite(options.confidence) || options.confidence < 0 || options.confidence > 1) {
+                return err('CONV_INVALID_CONFIDENCE', `Confidence must be in [0.0, 1.0], got ${options.confidence}`);
+            }
+        }
+        const groundingMode = options?.groundingMode ?? 'runtime_witness';
+        const evidenceRefs = options?.evidenceRefs ?? [];
+        const confidence = effectiveConfidence(options?.confidence, groundingMode, evidenceRefs);
+        const validAt = options?.validAt ?? time.nowISO();
+        const objectType = options?.objectType ?? 'string';
+        // Design Source §Grounding Mode Decision:
+        // evidence_path with empty evidenceRefs falls back to runtime_witness behavior.
+        // This prevents SC-11 rejection AND prevents confidence laundering.
+        const effectiveGroundingMode = (groundingMode === 'evidence_path' && evidenceRefs.length > 0)
+            ? 'evidence_path'
+            : 'runtime_witness';
+        const input = {
+            subject,
+            predicate,
+            object: { type: objectType, value },
+            confidence,
+            validAt,
+            missionId,
+            taskId,
+            evidenceRefs: effectiveGroundingMode === 'evidence_path'
+                ? evidenceRefs.map(ref => ({ type: ref.type, id: ref.id }))
+                : [],
+            groundingMode: effectiveGroundingMode,
+            ...(effectiveGroundingMode === 'runtime_witness' ? {
+                runtimeWitness: {
+                    witnessType: 'convenience',
+                    witnessedValues: { source: 'remember' },
+                    witnessTimestamp: validAt,
+                },
+            } : {}),
+        };
+        const result = claims.assertClaim(input);
+        if (!result.ok)
+            return result;
+        return ok({
+            claimId: result.value.claim.id,
+            confidence: result.value.claim.confidence,
+        });
+    }
+    /**
+     * 1-param remember: auto-generate subject from text hash.
+     */
+    function remember1(text, options) {
+        // Validate text is non-empty and not whitespace-only (I-CONV-09)
+        if (!text || text.trim().length === 0) {
+            return err('CONV_INVALID_TEXT', 'Text must be non-empty and not whitespace-only');
+        }
+        const subject = hashSubject(text);
+        return remember3(subject, 'observation.note', text, options);
+    }
+    return {
+        /**
+         * Phase 1 §1.1/§1.2: Store a belief.
+         *
+         * Overload resolution (I-CONV-12):
+         *   typeof secondArg === 'string' -> 3-param form
+         *   otherwise -> 1-param form
+         */
+        remember(subjectOrText, predicateOrOptions, value, options) {
+            if (typeof predicateOrOptions === 'string') {
+                // 3-param form: (subject, predicate, value, options?)
+                return remember3(subjectOrText, predicateOrOptions, value, options);
+            }
+            else {
+                // 1-param form: (text, options?)
+                return remember1(subjectOrText, predicateOrOptions);
+            }
+        },
+        /**
+         * Phase 1 §1.3: Retrieve beliefs.
+         *
+         * I-CONV-08: Excludes superseded claims by default.
+         */
+        recall(subject, predicate, options) {
+            const input = {
+                ...(subject ? { subject } : {}),
+                ...(predicate ? { predicate } : {}),
+                status: 'active',
+                ...(options?.minConfidence !== undefined ? { minConfidence: options.minConfidence } : {}),
+                limit: options?.limit ?? DEFAULT_RECALL_LIMIT,
+                includeEvidence: false,
+                includeRelationships: false,
+            };
+            const result = claims.queryClaims(input);
+            if (!result.ok)
+                return result;
+            // Map ClaimQueryResultItem -> BeliefView
+            let items = result.value.claims;
+            // I-CONV-08: Filter superseded unless explicitly included
+            if (!options?.includeSuperseded) {
+                items = items.filter(item => !item.superseded);
+            }
+            const beliefs = items.map(item => ({
+                claimId: item.claim.id,
+                subject: item.claim.subject,
+                predicate: item.claim.predicate,
+                value: String(item.claim.object.value),
+                confidence: item.claim.confidence,
+                validAt: item.claim.validAt,
+                createdAt: item.claim.createdAt,
+                superseded: item.superseded,
+                disputed: item.disputed,
+                // Phase 3: Cognitive Metabolism fields
+                effectiveConfidence: item.effectiveConfidence,
+                freshness: item.freshness,
+                stability: item.claim.stability,
+                lastAccessedAt: item.claim.lastAccessedAt,
+                accessCount: item.claim.accessCount,
+            }));
+            return ok(beliefs);
+        },
+        /**
+         * Phase 1 §1.4: Retract a belief.
+         *
+         * I-CONV-11: Delegates to ClaimApi.retractClaim().
+         * I-CONV-14: Maps system-call errors to convenience error codes.
+         */
+        forget(claimId, reason) {
+            const input = {
+                claimId: claimId,
+                reason: reason ?? 'Retracted via forget()',
+            };
+            const result = claims.retractClaim(input);
+            if (!result.ok) {
+                // Map well-known error codes
+                if (result.error.code === 'CLAIM_NOT_FOUND') {
+                    return err('CONV_CLAIM_NOT_FOUND', result.error.message);
+                }
+                if (result.error.code === 'CLAIM_ALREADY_RETRACTED') {
+                    return err('CONV_ALREADY_RETRACTED', result.error.message);
+                }
+                return result;
+            }
+            return ok(undefined);
+        },
+        /**
+         * Phase 1 §1.5: Create a relationship between two claims.
+         *
+         * DC-P1-804: Validates relationship type.
+         * DC-P1-805: Rejects self-reference.
+         */
+        connect(claimId1, claimId2, type) {
+            // Validate relationship type
+            if (!VALID_RELATIONSHIP_TYPES.includes(type)) {
+                return err('CONV_INVALID_RELATIONSHIP', `Invalid relationship type: ${type}. Must be one of: ${VALID_RELATIONSHIP_TYPES.join(', ')}`);
+            }
+            const input = {
+                fromClaimId: claimId1,
+                toClaimId: claimId2,
+                type: type,
+                missionId,
+            };
+            const result = claims.relateClaims(input);
+            if (!result.ok) {
+                // Map well-known error codes
+                if (result.error.code === 'SELF_REFERENCE') {
+                    return err('CONV_SELF_REFERENCE', result.error.message);
+                }
+                return result;
+            }
+            return ok(undefined);
+        },
+        /**
+         * Phase 1 §1.6: Batch-store categorized learnings.
+         *
+         * I-CONV-10: All-or-nothing transaction semantics.
+         * Uses SQLite BEGIN/COMMIT/ROLLBACK via getConnection().
+         */
+        reflect(entries) {
+            // Validate: non-empty entries
+            if (!entries || entries.length === 0) {
+                return err('CONV_EMPTY_ENTRIES', 'reflect() requires at least one entry');
+            }
+            // Validate: entries count limit (F-P1-008: DoS protection)
+            if (entries.length > MAX_REFLECT_ENTRIES) {
+                return err('CONV_ENTRIES_LIMIT', `reflect() accepts at most ${MAX_REFLECT_ENTRIES} entries, got ${entries.length}`);
+            }
+            // Pre-validate all entries before starting transaction
+            for (let i = 0; i < entries.length; i++) {
+                const entry = entries[i];
+                // Validate category
+                if (!VALID_CATEGORIES.includes(entry.category)) {
+                    return err('CONV_INVALID_CATEGORY', `Entry ${i}: invalid category '${entry.category}'. Must be one of: ${VALID_CATEGORIES.join(', ')}`);
+                }
+                // Validate statement length
+                if (entry.statement.length > MAX_STATEMENT_LENGTH) {
+                    return err('CONV_STATEMENT_TOO_LONG', `Entry ${i}: statement exceeds ${MAX_STATEMENT_LENGTH} characters (${entry.statement.length})`);
+                }
+                // Validate confidence if provided
+                if (entry.confidence !== undefined) {
+                    if (!Number.isFinite(entry.confidence) || entry.confidence < 0 || entry.confidence > 1) {
+                        return err('CONV_INVALID_CONFIDENCE', `Entry ${i}: confidence must be in [0.0, 1.0], got ${entry.confidence}`);
+                    }
+                }
+            }
+            // Transaction: all-or-nothing
+            const conn = getConnection();
+            conn.run('BEGIN');
+            try {
+                const claimIds = [];
+                for (const entry of entries) {
+                    const subject = hashSubject(entry.statement);
+                    const confidence = Math.min(entry.confidence ?? maxAutoConfidence, maxAutoConfidence);
+                    const validAt = time.nowISO();
+                    const input = {
+                        subject,
+                        predicate: `reflection.${entry.category}`,
+                        object: { type: 'string', value: entry.statement },
+                        confidence,
+                        validAt,
+                        missionId,
+                        taskId,
+                        evidenceRefs: [],
+                        groundingMode: 'runtime_witness',
+                        runtimeWitness: {
+                            witnessType: 'convenience',
+                            witnessedValues: { source: 'reflect', category: entry.category },
+                            witnessTimestamp: validAt,
+                        },
+                    };
+                    const result = claims.assertClaim(input);
+                    if (!result.ok) {
+                        conn.run('ROLLBACK');
+                        return result;
+                    }
+                    claimIds.push(result.value.claim.id);
+                }
+                conn.run('COMMIT');
+                return ok({ stored: claimIds.length, claimIds });
+            }
+            catch (catchErr) {
+                try {
+                    conn.run('ROLLBACK');
+                }
+                catch { /* already rolled back */ }
+                return err('CONV_BATCH_PARTIAL', `reflect() failed: ${String(catchErr)}`);
+            }
+        },
+        /**
+         * Phase 1 §1.7: Get system prompt instructions.
+         *
+         * I-CONV-18: Pure function, no I/O, deterministic.
+         */
+        promptInstructions() {
+            return generatePromptInstructions();
+        },
+        /**
+         * Phase 2 §2.4: Full-text search across claim content.
+         *
+         * Delegates to ClaimApi.searchClaims(). Maps SearchClaimResultItem -> SearchResult.
+         *
+         * Invariants: I-P2-02 (tenant isolation via facade), I-P2-05 (score), I-P2-07 (input validation)
+         * DCs: DC-P2-012 (limit validation), DC-P2-013 (empty query validation)
+         */
+        search(query, options) {
+            // I-P2-07: Validate query is non-empty
+            if (!query || query.trim().length === 0) {
+                return err('CONV_SEARCH_EMPTY_QUERY', 'Search query must be non-empty and not whitespace-only');
+            }
+            // I-P2-07: Validate limit
+            const limit = options?.limit ?? DEFAULT_SEARCH_LIMIT;
+            if (limit <= 0 || limit > MAX_SEARCH_LIMIT) {
+                return err('CONV_SEARCH_INVALID_LIMIT', `Search limit must be in [1, ${MAX_SEARCH_LIMIT}], got ${limit}`);
+            }
+            const input = {
+                query: query.trim(),
+                ...(options?.minConfidence !== undefined ? { minConfidence: options.minConfidence } : {}),
+                limit,
+                ...(options?.includeSuperseded !== undefined ? { includeSuperseded: options.includeSuperseded } : {}),
+            };
+            const result = claims.searchClaims(input);
+            if (!result.ok)
+                return result;
+            // Map SearchClaimResultItem -> SearchResult (convenience type)
+            const searchResults = result.value.results.map(item => ({
+                belief: {
+                    claimId: item.claim.id,
+                    subject: item.claim.subject,
+                    predicate: item.claim.predicate,
+                    value: String(item.claim.object.value),
+                    confidence: item.claim.confidence,
+                    validAt: item.claim.validAt,
+                    createdAt: item.claim.createdAt,
+                    superseded: item.superseded,
+                    disputed: item.disputed,
+                    // Phase 3: Cognitive Metabolism fields
+                    effectiveConfidence: item.effectiveConfidence,
+                    freshness: item.freshness,
+                    stability: item.claim.stability,
+                    lastAccessedAt: item.claim.lastAccessedAt,
+                    accessCount: item.claim.accessCount,
+                },
+                relevance: item.relevance,
+                score: item.score,
+            }));
+            return ok(searchResults);
+        },
+    };
+}
+//# sourceMappingURL=convenience_layer.js.map