@plur-ai/core 0.9.3 → 0.9.4

package/dist/index.js

@@ -1,12 +1,15 @@
 import {
   computeIdf,
+  embedderStatus,
   embeddingSearch,
   embeddingSearchWithScores,
   engramSearchText,
   ftsScore,
   ftsTokenize,
-  searchEngrams
-} from "./chunk-IGGMRXAB.js";
+  resetEmbedder,
+  searchEngrams,
+  setEmbeddingsEnabled
+} from "./chunk-ZY4R3VEG.js";
 import {
   EngramSchemaPassthrough,
   appendHistory,
@@ -26,19 +29,18 @@ import {
   readHistoryForEngram,
   saveEngrams,
   storePrefix
-} from "./chunk-3ZPTRZE3.js";
+} from "./chunk-EQPTF4JZ.js";
 import {
   atomicWrite,
   getSyncStatus,
   sync,
   withLock
 } from "./chunk-PRK3B7WR.js";
-import "./chunk-2ZDO52B4.js";
 
 // src/index.ts
 import * as fs4 from "fs";
-import * as os from "os";
-import * as path3 from "path";
+import { tmpdir } from "os";
+import { join as join5, dirname as dirname2, basename as basename2 } from "path";
 import yaml6 from "js-yaml";
 
 // src/storage.ts
@@ -244,6 +246,9 @@ var StorageConfigSchema = z.object({
   backend: z.enum(["yaml", "sqlite"]).default("yaml"),
   path: z.string().optional()
 }).partial();
+var EmbeddingsConfigSchema = z.object({
+  enabled: z.boolean().default(true)
+}).partial();
 var PlurConfigSchema = z.object({
   auto_learn: z.boolean().default(true),
   auto_capture: z.boolean().default(true),
@@ -261,6 +266,7 @@ var PlurConfigSchema = z.object({
   allow_secrets: z.boolean().default(false),
   index: z.boolean().default(true),
   storage: StorageConfigSchema.default({}),
+  embeddings: EmbeddingsConfigSchema.default({}),
   stores: z.array(StoreEntrySchema).default([]),
   llm: LlmTierConfigSchema.default({}),
   profile: ProfileConfigSchema.default({}),
@@ -450,6 +456,7 @@ var DEFAULT_MAX_TOKENS = 8e3;
 var DEFAULT_MIN_RELEVANCE = 0.3;
 var MAX_PER_PACK = 5;
 var MAX_PER_DOMAIN = 10;
+var PINNED_TOKEN_BUDGET_RATIO = 0.5;
 var DIP19_CONSIDER_MAX = 5;
 var DIP19_CONSIDER_BUDGET = 200;
 function getPackMetadata(manifest) {
@@ -528,7 +535,11 @@ function scoreEngram(engram, promptLower, promptWords, packMatchTerms, scopeFilt
   for (const word of promptWords) {
     if (statementWords.has(word)) termHits += 0.5;
   }
-  if (termHits === 0) return 0;
+  const isPinned = engram.pinned === true;
+  if (termHits === 0 && !isPinned) return 0;
+  if (termHits === 0 && isPinned) {
+    termHits = 0.5;
+  }
   let rs = isPack ? engram.activation.retrieval_strength : decayedStrength(engram.activation.retrieval_strength, daysSince(engram.activation.last_accessed));
   if (!isPack) {
     const fb = engram.feedback_signals;
@@ -543,6 +554,7 @@ function scoreEngram(engram, promptLower, promptWords, packMatchTerms, scopeFilt
     else if (netFeedback < 0) score *= Math.max(1 + netFeedback * 0.1, 0.5);
   }
   if (engram.consolidated) score *= 1.1;
+  if (isPinned) score *= 2;
   const emotionalWeight = engram.episodic?.emotional_weight ?? 5;
   score *= 1 + (emotionalWeight - 5) * 0.04;
   return score;
@@ -552,7 +564,21 @@ function fillTokenBudget(scored, maxTokens) {
   const packCounts = /* @__PURE__ */ new Map();
   const domainCounts = /* @__PURE__ */ new Map();
   let tokensUsed = 0;
-  for (const engram of scored) {
+  const pinned = scored.filter((e) => e.pinned === true);
+  const unpinned = scored.filter((e) => e.pinned !== true);
+  const pinnedBudget = Math.floor(maxTokens * PINNED_TOKEN_BUDGET_RATIO);
+  for (const engram of pinned) {
+    const cost = estimateTokens(engram);
+    if (tokensUsed + cost > maxTokens) continue;
+    if (tokensUsed + cost > pinnedBudget) continue;
+    result.push(engram);
+    tokensUsed += cost;
+    const pack = engram.pack ?? "__personal__";
+    packCounts.set(pack, (packCounts.get(pack) ?? 0) + 1);
+    const topDomain = (engram.domain ?? "__none__").split(".")[0];
+    domainCounts.set(topDomain, (domainCounts.get(topDomain) ?? 0) + 1);
+  }
+  for (const engram of unpinned) {
     const cost = estimateTokens(engram);
     if (tokensUsed + cost > maxTokens) continue;
     const pack = engram.pack ?? "__personal__";
@@ -586,7 +612,7 @@ function selectAndSpread(ctx, personalEngrams, packs, config, embeddingBoosts) {
     engramMap.set(engram.id, engram);
     let raw = scoreEngram(engram, promptLower, promptWords, [], ctx.scope, false);
     const embBoost = embeddingBoosts?.get(engram.id) ?? 0;
-    if (raw === 0 && embBoost > 0.3) {
+    if (raw === 0 && embBoost > 0.5) {
       raw = embBoost * 2;
     } else if (raw > 0 && embBoost > 0) {
       raw += embBoost;
@@ -611,7 +637,7 @@ function selectAndSpread(ctx, personalEngrams, packs, config, embeddingBoosts) {
       engramMap.set(engram.id, engram);
       let raw = scoreEngram(engram, promptLower, promptWords, matchTerms, ctx.scope, true);
       const embBoost = embeddingBoosts?.get(engram.id) ?? 0;
-      if (raw === 0 && embBoost > 0.3) {
+      if (raw === 0 && embBoost > 0.5) {
         raw = embBoost * 2;
       } else if (raw > 0 && embBoost > 0) {
         raw += embBoost;
@@ -631,7 +657,7 @@ function selectAndSpread(ctx, personalEngrams, packs, config, embeddingBoosts) {
     aBoosts.set(e.id, aBoost);
     e.score = e.keyword_match + aBoost;
   }
-  const filtered = scored.filter((s) => s.score >= minRelevance);
+  const filtered = scored.filter((s) => s.pinned === true || s.score >= minRelevance);
   filtered.sort((a, b) => b.score - a.score);
   const { selected: directives, tokens_used: directiveTokens } = fillTokenBudget(filtered, maxTokens);
   const directiveIds = new Set(directives.map((e) => e.id));
@@ -772,8 +798,8 @@ function generateEpisodeId() {
   const rand = Math.random().toString(36).slice(2, 6);
   return `EP-${ts}-${rand}`;
 }
-function captureEpisode(path4, summary, context) {
-  const episodes = loadEpisodes(path4);
+function captureEpisode(path3, summary, context) {
+  const episodes = loadEpisodes(path3);
   const episode = {
     id: generateEpisodeId(),
     summary,
@@ -784,11 +810,11 @@ function captureEpisode(path4, summary, context) {
     timestamp: (/* @__PURE__ */ new Date()).toISOString()
   };
   episodes.push(episode);
-  atomicWrite(path4, yaml2.dump(episodes, { lineWidth: 120, noRefs: true }));
+  atomicWrite(path3, yaml2.dump(episodes, { lineWidth: 120, noRefs: true }));
   return episode;
 }
-function queryTimeline(path4, query) {
-  let episodes = loadEpisodes(path4);
+function queryTimeline(path3, query) {
+  let episodes = loadEpisodes(path3);
   if (query?.since) episodes = episodes.filter((e) => new Date(e.timestamp) >= query.since);
   if (query?.until) episodes = episodes.filter((e) => new Date(e.timestamp) <= query.until);
   if (query?.agent) episodes = episodes.filter((e) => e.agent === query.agent);
@@ -799,10 +825,10 @@ function queryTimeline(path4, query) {
   }
   return episodes;
 }
-function loadEpisodes(path4) {
-  if (!existsSync4(path4)) return [];
+function loadEpisodes(path3) {
+  if (!existsSync4(path3)) return [];
   try {
-    const raw = yaml2.load(readFileSync2(path4, "utf8"));
+    const raw = yaml2.load(readFileSync2(path3, "utf8"));
     return Array.isArray(raw) ? raw : [];
   } catch {
     return [];
@@ -903,7 +929,13 @@ function isAggregationQuery(query) {
   return AGGREGATION_PATTERNS.some((p) => p.test(query));
 }
 async function hybridSearch(engrams, query, limit, storagePath) {
-  if (engrams.length === 0) return [];
+  const result = await hybridSearchWithMeta(engrams, query, limit, storagePath);
+  return result.engrams;
+}
+async function hybridSearchWithMeta(engrams, query, limit, storagePath) {
+  if (engrams.length === 0) {
+    return { engrams: [], mode: "hybrid", embedderError: null };
+  }
   const exhaustive = isAggregationQuery(query);
   const effectiveLimit = exhaustive ? Math.max(limit, 50) : limit;
   const bm25Limit = Math.min(engrams.length, exhaustive ? effectiveLimit * 5 : effectiveLimit * 3);
@@ -912,8 +944,23 @@ async function hybridSearch(engrams, query, limit, storagePath) {
     Promise.resolve(searchEngrams(engrams, query, bm25Limit)),
     embeddingSearch(engrams, query, embLimit, storagePath)
   ]);
+  const status = embedderStatus();
+  let mode;
+  let embedderError = null;
+  if (status.disabled) {
+    mode = "bm25-only";
+  } else if (!status.available || embResults.length === 0 && !!status.lastError) {
+    mode = "hybrid-degraded";
+    embedderError = status.lastError;
+  } else {
+    mode = "hybrid";
+  }
   const merged = rrfMerge([bm25Results, embResults]);
-  return merged.slice(0, effectiveLimit);
+  return {
+    engrams: merged.slice(0, effectiveLimit),
+    mode,
+    embedderError
+  };
 }
 
 // src/query-expansion.ts
@@ -1585,7 +1632,7 @@ async function computeSimilarityMatrix(templates) {
   const n = templates.length;
   const matrix = Array.from({ length: n }, () => Array(n).fill(0));
   try {
-    const { embed, cosineSimilarity } = await import("./embeddings-ZRT6IRPA.js");
+    const { embed, cosineSimilarity } = await import("./embeddings-3EXLC3EH.js");
     const embeddings = [];
     for (const t of templates) {
       embeddings.push(await embed(t));
@@ -2936,6 +2983,192 @@ function isNewer(a, b) {
   return false;
 }
 
+// src/schemas/capsule.ts
+import { z as z3 } from "zod";
+var CAPSULE_MAGIC = Buffer.from([80, 76, 85, 82]);
+var CAPSULE_MAGIC_HEX = "50 4c 55 52";
+var FORMAT_VERSION_V1 = 1;
+var SUPPORTED_FORMAT_VERSIONS = [FORMAT_VERSION_V1];
+var CAPSULE_FLAGS = {
+  SIGNED: 1 << 0,
+  COMPRESSED: 1 << 1
+};
+var CAPSULE_FLAG_RESERVED_MASK = 65532;
+var PREAMBLE_LEN = 12;
+var CAPSULE_SIZE_LIMITS = {
+  SOFT_BYTES: 100 * 1024 * 1024,
+  HARD_BYTES: 1024 * 1024 * 1024
+};
+var ED25519_SIG_LEN = 64;
+var ManifestSummarySchema = z3.object({
+  name: z3.string().min(1),
+  version: z3.string().min(1),
+  creator: z3.string().optional(),
+  engram_count: z3.number().int().min(0),
+  domain: z3.string().optional(),
+  license: z3.string().default("cc-by-sa-4.0")
+});
+var PayloadDescriptorSchema = z3.object({
+  compression: z3.enum(["gzip", "none"]),
+  size_compressed: z3.number().int().min(0),
+  size_uncompressed: z3.number().int().min(0),
+  sha256: z3.string().regex(/^[0-9a-f]{64}$/, "sha256 must be 64 lowercase hex chars")
+});
+var ProducerSchema = z3.object({
+  tool: z3.string().min(1),
+  version: z3.string().min(1),
+  agent_id: z3.string().optional()
+});
+var SignerSchema = z3.object({
+  algo: z3.literal("ed25519"),
+  public_key: z3.string().min(1),
+  key_id: z3.string().optional()
+});
+var CapsuleHeaderSchema = z3.object({
+  schema: z3.literal("plur.capsule/1"),
+  product_type: z3.enum(["engram-pack", "skill"]),
+  manifest_summary: ManifestSummarySchema,
+  payload: PayloadDescriptorSchema,
+  created_at: z3.string().datetime({ offset: true }),
+  producer: ProducerSchema,
+  signer: SignerSchema.nullable().default(null)
+});
+function parseCapsulePreamble(buf) {
+  if (buf.length < PREAMBLE_LEN) {
+    throw new Error(`capsule: truncated preamble (got ${buf.length} bytes, need ${PREAMBLE_LEN})`);
+  }
+  if (buf.compare(CAPSULE_MAGIC, 0, 4, 0, 4) !== 0) {
+    throw new Error(`capsule: bad magic (expected ${CAPSULE_MAGIC_HEX})`);
+  }
+  const formatVersion = buf.readUInt16LE(4);
+  if (!SUPPORTED_FORMAT_VERSIONS.includes(formatVersion)) {
+    throw new Error(`capsule: unsupported FormatVersion 0x${formatVersion.toString(16).padStart(4, "0")}`);
+  }
+  const flags = buf.readUInt16LE(6);
+  if ((flags & CAPSULE_FLAG_RESERVED_MASK) !== 0) {
+    throw new Error(`capsule: reserved flag bits set (flags=0x${flags.toString(16).padStart(4, "0")})`);
+  }
+  const headerLen = buf.readUInt32LE(8);
+  if (headerLen === 0) {
+    throw new Error("capsule: HeaderLen must be > 0");
+  }
+  if (headerLen > CAPSULE_SIZE_LIMITS.HARD_BYTES) {
+    throw new Error(`capsule: HeaderLen ${headerLen} exceeds hard size limit`);
+  }
+  return { formatVersion, flags, headerLen };
+}
+function serializeCapsulePreamble(p) {
+  const buf = Buffer.alloc(PREAMBLE_LEN);
+  CAPSULE_MAGIC.copy(buf, 0);
+  buf.writeUInt16LE(p.formatVersion, 4);
+  buf.writeUInt16LE(p.flags, 6);
+  buf.writeUInt32LE(p.headerLen, 8);
+  return buf;
+}
+function hasFlag(flags, flag) {
+  return (flags & flag) === flag;
+}
+
+// src/capsule.ts
+import { createHash as createHash2 } from "crypto";
+function writeCapsule(opts) {
+  const compression = opts.compression ?? "gzip";
+  const productType = opts.productType ?? "engram-pack";
+  const createdAt = opts.createdAt ?? (/* @__PURE__ */ new Date()).toISOString();
+  const signer = opts.signer ?? null;
+  if (signer !== null && (!opts.signature || opts.signature.length !== ED25519_SIG_LEN)) {
+    throw new Error(`writeCapsule: signer set but signature missing or not ${ED25519_SIG_LEN} bytes`);
+  }
+  if (signer === null && opts.signature) {
+    throw new Error("writeCapsule: signature provided without signer \u2014 refuse ambiguous envelope");
+  }
+  const sha256 = createHash2("sha256").update(opts.payload).digest("hex");
+  const sizeCompressed = opts.payload.length;
+  const sizeUncompressed = opts.sizeUncompressed ?? sizeCompressed;
+  const header = CapsuleHeaderSchema.parse({
+    schema: "plur.capsule/1",
+    product_type: productType,
+    manifest_summary: opts.manifestSummary,
+    payload: {
+      compression,
+      size_compressed: sizeCompressed,
+      size_uncompressed: sizeUncompressed,
+      sha256
+    },
+    created_at: createdAt,
+    producer: opts.producer,
+    signer
+  });
+  const headerJson = Buffer.from(JSON.stringify(header), "utf-8");
+  let flags = 0;
+  if (compression === "gzip") flags |= CAPSULE_FLAGS.COMPRESSED;
+  if (signer !== null) flags |= CAPSULE_FLAGS.SIGNED;
+  const preamble = serializeCapsulePreamble({
+    formatVersion: FORMAT_VERSION_V1,
+    flags,
+    headerLen: headerJson.length
+  });
+  const totalLen = PREAMBLE_LEN + headerJson.length + opts.payload.length + (signer !== null ? ED25519_SIG_LEN : 0);
+  if (totalLen > CAPSULE_SIZE_LIMITS.HARD_BYTES) {
+    throw new Error(`writeCapsule: capsule size ${totalLen} exceeds hard limit`);
+  }
+  const parts = [preamble, headerJson, opts.payload];
+  if (signer !== null && opts.signature) parts.push(opts.signature);
+  return Buffer.concat(parts, totalLen);
+}
+function readCapsule(buf) {
+  if (buf.length > CAPSULE_SIZE_LIMITS.HARD_BYTES) {
+    throw new Error(`readCapsule: capsule size ${buf.length} exceeds hard limit`);
+  }
+  const preamble = parseCapsulePreamble(buf);
+  const headerStart = PREAMBLE_LEN;
+  const headerEnd = headerStart + preamble.headerLen;
+  if (buf.length < headerEnd) {
+    throw new Error(`readCapsule: truncated header (need ${headerEnd} bytes, got ${buf.length})`);
+  }
+  const headerJson = buf.subarray(headerStart, headerEnd).toString("utf-8");
+  let parsedHeader;
+  try {
+    parsedHeader = JSON.parse(headerJson);
+  } catch (err) {
+    throw new Error(`readCapsule: malformed header JSON \u2014 ${err.message}`);
+  }
+  const header = CapsuleHeaderSchema.parse(parsedHeader);
+  const isSigned = hasFlag(preamble.flags, CAPSULE_FLAGS.SIGNED);
+  const sigLen = isSigned ? ED25519_SIG_LEN : 0;
+  const payloadEnd = buf.length - sigLen;
+  if (payloadEnd < headerEnd) {
+    throw new Error("readCapsule: payload region underflow");
+  }
+  const payload = buf.subarray(headerEnd, payloadEnd);
+  const signature = isSigned ? buf.subarray(payloadEnd) : null;
+  if (payload.length !== header.payload.size_compressed) {
+    throw new Error(
+      `readCapsule: payload size mismatch (header=${header.payload.size_compressed}, actual=${payload.length})`
+    );
+  }
+  const actualSha = createHash2("sha256").update(payload).digest("hex");
+  if (actualSha !== header.payload.sha256) {
+    throw new Error(`readCapsule: integrity mismatch (header=${header.payload.sha256}, actual=${actualSha})`);
+  }
+  const compressionFlagSet = hasFlag(preamble.flags, CAPSULE_FLAGS.COMPRESSED);
+  const headerSaysCompressed = header.payload.compression === "gzip";
+  if (compressionFlagSet !== headerSaysCompressed) {
+    throw new Error(
+      `readCapsule: COMPRESSED flag (${compressionFlagSet}) disagrees with header.payload.compression (${header.payload.compression})`
+    );
+  }
+  return { header, payload: Buffer.from(payload), signature: signature ? Buffer.from(signature) : null };
+}
+function verifyCapsuleIntegrity(buf) {
+  try {
+    readCapsule(buf);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 // src/index.ts
 var COMMITMENT_MULTIPLIER = {
   locked: 1,
@@ -2973,6 +3206,9 @@ var Plur = class {
     if (this.config.index) {
       this.indexedStorage = new IndexedStorage(this.paths.engrams, this.paths.db, this.config.stores);
     }
+    if (this.config.embeddings?.enabled === false) {
+      setEmbeddingsEnabled(false, "embeddings disabled in config.yaml (embeddings.enabled = false)");
+    }
   }
   /**
    * Load engrams from primary store + all configured stores, with mtime-based caching.
@@ -3014,17 +3250,17 @@ var Plur = class {
     return all;
   }
   /** Load engrams from a path with mtime-based caching */
-  _loadCached(path4) {
+  _loadCached(path3) {
     let mtime;
     try {
-      mtime = fs4.statSync(path4, { bigint: true }).mtimeNs;
+      mtime = fs4.statSync(path3, { bigint: true }).mtimeNs;
     } catch {
       return [];
     }
-    const cached = this._engramCache.get(path4);
+    const cached = this._engramCache.get(path3);
     if (cached && cached.mtime === mtime) return cached.engrams;
-    const engrams = loadEngrams(path4);
-    this._engramCache.set(path4, { mtime, engrams });
+    const engrams = loadEngrams(path3);
+    this._engramCache.set(path3, { mtime, engrams });
     return engrams;
   }
   /**
@@ -3038,9 +3274,9 @@ var Plur = class {
    * invalidation on write removes the filesystem as a source of cache
    * freshness and closes the race. See issue #25.
    */
-  _writeEngrams(path4, engrams) {
-    saveEngrams(path4, engrams);
-    this._engramCache.delete(path4);
+  _writeEngrams(path3, engrams) {
+    saveEngrams(path3, engrams);
+    this._engramCache.delete(path3);
   }
   /** Find which store owns an engram by ID. For namespaced IDs, strips prefix to find in store. */
   _findEngramStore(id) {
@@ -3168,7 +3404,8 @@ var Plur = class {
           narrower: [],
           related: [],
           conflicts: conflictIds
-        } : void 0
+        } : void 0,
+        pinned: context?.pinned === true ? true : void 0
       };
       engrams.push(engram);
       this._writeEngrams(this.paths.engrams, engrams);
@@ -3201,12 +3438,12 @@ var Plur = class {
   }
   /** Async learn with LLM-driven deduplication (Ideas 1+2+19). */
   async learnAsync(statement, context) {
-    const { learnAsync: learnAsyncImpl } = await import("./learn-async-R5KZ5EWF.js");
+    const { learnAsync: learnAsyncImpl } = await import("./learn-async-IISWD7HC.js");
     return learnAsyncImpl(this._learnAsyncDeps(), statement, context);
   }
   /** Batch learn with LLM dedup. */
   async learnBatch(statements, llm) {
-    const { learnBatch: learnBatchImpl } = await import("./learn-async-R5KZ5EWF.js");
+    const { learnBatch: learnBatchImpl } = await import("./learn-async-IISWD7HC.js");
     return learnBatchImpl(this._learnAsyncDeps(), statements, llm);
   }
   /**
@@ -3247,6 +3484,26 @@ var Plur = class {
     this._reactivateResults(results);
     return results;
   }
+  /**
+   * Hybrid search with diagnostic metadata — returns both the engrams and
+   * whether embeddings actually contributed (mode: "hybrid" vs "hybrid-degraded").
+   * Use this when you want to surface degraded-mode warnings to users.
+   */
+  async recallHybridWithMeta(query, options) {
+    const filtered = this._filterEngrams(options);
+    const limit = options?.limit ?? 20;
+    const result = await hybridSearchWithMeta(filtered, query, limit, this.paths.root);
+    this._reactivateResults(result.engrams);
+    return result;
+  }
+  /** Inspect embedder availability without forcing a load. */
+  embedderStatus() {
+    return embedderStatus();
+  }
+  /** Reset cached embedder failure state — next call will retry the model load. */
+  resetEmbedder() {
+    resetEmbedder();
+  }
   /** Embedding search returning {engram, score}[] with cosine similarity scores. Async, no API calls. */
   async similaritySearch(query, options) {
     const filtered = this._filterEngrams(options);
@@ -3375,11 +3632,16 @@ var Plur = class {
     let embeddingBoosts;
     try {
       const engrams = this._loadAllEngrams().filter((e) => e.status === "active");
-      const results = await embeddingSearch(engrams, task, engrams.length, this.paths.root);
+      const results = await embeddingSearchWithScores(
+        engrams,
+        task,
+        engrams.length,
+        this.paths.root
+      );
       if (results.length > 0) {
         embeddingBoosts = /* @__PURE__ */ new Map();
-        for (let i = 0; i < results.length; i++) {
-          embeddingBoosts.set(results[i].id, 1 / (1 + i * 0.1));
+        for (const r of results) {
+          embeddingBoosts.set(r.engram.id, r.score);
         }
       }
     } catch {
@@ -3510,6 +3772,28 @@ var Plur = class {
       return true;
     });
   }
+  /**
+   * Toggle the always-load (pinned) flag for an engram.
+   * Returns the updated engram on success, null if not found.
+   */
+  setPinned(id, pinned) {
+    return withLock(this.paths.engrams, () => {
+      const engrams = loadEngrams(this.paths.engrams);
+      const idx = engrams.findIndex((e2) => e2.id === id);
+      if (idx === -1) return null;
+      const e = engrams[idx];
+      const updated = { ...e, pinned: pinned === true ? true : void 0 };
+      engrams[idx] = updated;
+      this._writeEngrams(this.paths.engrams, engrams);
+      this._syncIndex();
+      return updated;
+    });
+  }
+  /** List engrams that have pinned: true. */
+  listPinned() {
+    const all = this._loadAllEngrams();
+    return all.filter((e) => e.pinned === true && e.status === "active");
+  }
   /** Set engram status to 'retired'. Supports primary and store engrams. */
   forget(id, reason) {
     const foundInPrimary = withLock(this.paths.engrams, () => {
@@ -3875,20 +4159,19 @@ Generate an improved version of the procedure that prevents this failure. Return
   autoDiscoverStores(cwd) {
     const startDir = cwd || process.cwd();
     const discovered = [];
-    const tmpDir = os.tmpdir();
+    const tmpDir = tmpdir();
     if (this.paths.root.startsWith(tmpDir) || this.paths.root.startsWith("/tmp/")) {
       return discovered;
     }
     const knownPaths = new Set((this.config.stores ?? []).map((s) => s.path));
-    const primaryDir = path3.dirname(this.paths.engrams);
+    const primaryDir = dirname2(this.paths.engrams);
     let dir = startDir;
-    const { join: join5, dirname: dirname3, basename: basename2 } = path3;
     const visited = /* @__PURE__ */ new Set();
     while (dir && !visited.has(dir)) {
       visited.add(dir);
       const candidate = join5(dir, ".plur", "engrams.yaml");
       if (join5(dir, ".plur") === primaryDir) {
-        dir = dirname3(dir);
+        dir = dirname2(dir);
         continue;
       }
       if (fs4.existsSync(candidate) && !knownPaths.has(candidate)) {
@@ -3907,7 +4190,7 @@ Generate an improved version of the procedure that prevents this failure. Return
         logger.info(`Auto-discovered project store: ${candidate} (${scope})`);
       }
       if (fs4.existsSync(join5(dir, ".git"))) break;
-      const parent = dirname3(dir);
+      const parent = dirname2(dir);
       if (parent === dir) break;
       dir = parent;
     }
@@ -3936,18 +4219,32 @@ Generate an improved version of the procedure that prevents this failure. Return
 };
 export {
   ALL_MIGRATIONS,
+  CAPSULE_FLAGS,
+  CAPSULE_FLAG_RESERVED_MASK,
+  CAPSULE_MAGIC,
+  CAPSULE_MAGIC_HEX,
+  CAPSULE_SIZE_LIMITS,
   COMMITMENT_MULTIPLIER,
   CURRENT_SCHEMA_VERSION,
+  CapsuleHeaderSchema,
   DomainCoverageSchema,
+  ED25519_SIG_LEN,
   EvidenceEntrySchema,
+  FORMAT_VERSION_V1,
   FalsificationSchema,
   HierarchyPositionSchema,
   IndexedStorage,
+  ManifestSummarySchema,
   MetaConfidenceSchema,
   MetaFieldSchema,
   PLATITUDE_PATTERNS,
+  PREAMBLE_LEN,
+  PayloadDescriptorSchema,
   Plur,
+  ProducerSchema,
+  SUPPORTED_FORMAT_VERSIONS,
   SessionBreadcrumbs,
+  SignerSchema,
   SqliteStore,
   StructuralTemplateSchema,
   YamlStore,
@@ -3986,6 +4283,7 @@ export {
   getCachedUpdateCheck,
   getProfileForInjection,
   getSchemaVersion,
+  hasFlag,
   isPlatitude,
   listHistoryMonths,
   loadProfileCache,
@@ -3994,8 +4292,10 @@ export {
   needsSummary,
   normalizeStatement,
   organizeHierarchy,
+  parseCapsulePreamble,
   parseDedupResponse,
   profileNeedsRegeneration,
+  readCapsule,
   readHistory,
   readHistoryForEngram,
   recallAuto,
@@ -4005,9 +4305,12 @@ export {
   saveProfileCache,
   selectModel,
   selectModelForOperation,
+  serializeCapsulePreamble,
   setSchemaVersion,
   strengthToStatus,
   tokenSimilarity,
   validateMetaEngram,
-  withAsyncLock
+  verifyCapsuleIntegrity,
+  withAsyncLock,
+  writeCapsule
 };

package/dist/{learn-async-R5KZ5EWF.js → learn-async-IISWD7HC.js}

@@ -6,11 +6,10 @@ import {
   logger,
   parseDedupResponse,
   saveEngrams
-} from "./chunk-3ZPTRZE3.js";
+} from "./chunk-EQPTF4JZ.js";
 import {
   withLock
 } from "./chunk-PRK3B7WR.js";
-import "./chunk-2ZDO52B4.js";
 
 // src/learn-async.ts
 function executeDedupDecision(deps, statement, context, decision, targetId, conflicts) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plur-ai/core",
-  "version": "0.9.3",
+  "version": "0.9.4",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",