zam-core 0.7.0 → 0.7.1

package/.agent/skills/zam/SKILL.md

@@ -147,6 +147,12 @@ zam token find --query "<keywords>"
 ```
 Only register genuinely new concepts. Reuse existing slugs where the concept matches. Note that `zam token find` matches paraphrases semantically.
 
+After deduplication and before registering a new token, check for existing semantically related tokens that could be prerequisites ("foundations"):
+```bash
+echo '{"concept":"<concept>","question":"<question>","domain":"<domain>"}' | zam bridge suggest-foundations
+```
+Present non-flagged suggestions to the user ("Related existing concept X — link it as a foundation?"); on approval link via the existing prereq path after registering.
+
 **Register tokens and prerequisites:**
 
 As the frontier model, YOU author both the concept and the recall question. The
@@ -371,6 +377,12 @@ A token should be decomposed when ALL of the following hold:
 After a rating of 1, pause. Do not just re-ask the same question or move on.
 Ask yourself: **"What would the user have needed to know to answer this?"**
 
+Always check for existing related foundation tokens first:
+```bash
+echo '{"slug":"<failed-token-slug>"}' | zam bridge suggest-foundations
+```
+Offer existing tokens returned as suggestions to the user first (linking them feeds the existing `confirmFoundations` path with `exists: true` and `slug`). Only generate NEW foundation proposals via the LLM for gaps that the suggestions do not cover.
+
 | Symptom | Missing foundation | Create Bloom 1-2 token for |
 |---------|-------------------|---------------------------|
 | Couldn't name key terms | Factual recall | Definitions, terminology |

package/.agents/skills/zam/SKILL.md

@@ -178,6 +178,12 @@ zam token find --query "<keywords>"
 ```
 Only register genuinely new concepts. Reuse existing slugs where the concept matches. Note that `zam token find` matches paraphrases semantically.
 
+After deduplication and before registering a new token, check for existing semantically related tokens that could be prerequisites ("foundations"):
+```bash
+echo '{"concept":"<concept>","question":"<question>","domain":"<domain>"}' | zam bridge suggest-foundations
+```
+Present non-flagged suggestions to the user ("Related existing concept X — link it as a foundation?"); on approval link via the existing prereq path after registering.
+
 **Register tokens and prerequisites:**
 
 As the frontier model, author both the concept and the recall question. The
@@ -467,6 +473,12 @@ A token should be decomposed when ALL of the following hold:
 After a rating of 1, pause. Do not just re-ask the same question or move on.
 Ask yourself: **"What would the user have needed to know to answer this?"**
 
+Always check for existing related foundation tokens first:
+```bash
+echo '{"slug":"<failed-token-slug>"}' | zam bridge suggest-foundations
+```
+Offer existing tokens returned as suggestions to the user first (linking them feeds the existing `confirmFoundations` path with `exists: true` and `slug`). Only generate NEW foundation proposals via the LLM for gaps that the suggestions do not cover.
+
 | Symptom | Missing foundation | Create Bloom 1-2 token for |
 |---------|-------------------|---------------------------|
 | Couldn't name key terms | Factual recall | Definitions, terminology |

package/.claude/skills/zam/SKILL.md

@@ -147,6 +147,12 @@ zam token find --query "<keywords>"
 ```
 Only register genuinely new concepts. Reuse existing slugs where the concept matches. Note that `zam token find` matches paraphrases semantically.
 
+After deduplication and before registering a new token, check for existing semantically related tokens that could be prerequisites ("foundations"):
+```bash
+echo '{"concept":"<concept>","question":"<question>","domain":"<domain>"}' | zam bridge suggest-foundations
+```
+Present non-flagged suggestions to the user ("Related existing concept X — link it as a foundation?"); on approval link via the existing prereq path after registering.
+
 **Register tokens and prerequisites:**
 
 As the frontier model, YOU author both the concept and the recall question. The
@@ -371,6 +377,12 @@ A token should be decomposed when ALL of the following hold:
 After a rating of 1, pause. Do not just re-ask the same question or move on.
 Ask yourself: **"What would the user have needed to know to answer this?"**
 
+Always check for existing related foundation tokens first:
+```bash
+echo '{"slug":"<failed-token-slug>"}' | zam bridge suggest-foundations
+```
+Offer existing tokens returned as suggestions to the user first (linking them feeds the existing `confirmFoundations` path with `exists: true` and `slug`). Only generate NEW foundation proposals via the LLM for gaps that the suggestions do not cover.
+
 | Symptom | Missing foundation | Create Bloom 1-2 token for |
 |---------|-------------------|---------------------------|
 | Couldn't name key terms | Factual recall | Definitions, terminology |

package/dist/cli/index.js

@@ -2219,9 +2219,9 @@ async function buildAncestorMap(db) {
   }
   return map;
 }
-async function wouldCreateCycle(db, tokenId, requiresId) {
+async function wouldCreateCycle(db, tokenId, requiresId, ancestors) {
   if (tokenId === requiresId) return true;
-  const ancestors = await buildAncestorMap(db);
+  const map = ancestors ?? await buildAncestorMap(db);
   const visited = /* @__PURE__ */ new Set();
   const queue = [requiresId];
   while (queue.length > 0) {
@@ -2229,7 +2229,7 @@ async function wouldCreateCycle(db, tokenId, requiresId) {
     if (current === tokenId) return true;
     if (visited.has(current)) continue;
     visited.add(current);
-    const parents = ancestors.get(current);
+    const parents = map.get(current);
     if (parents) {
       for (const parent of parents) {
         if (!visited.has(parent)) queue.push(parent);
@@ -4789,6 +4789,71 @@ async function searchTokensHybrid(db, query, opts) {
   return results.slice(0, limit);
 }
 
+// src/kernel/search/suggestions.ts
+async function suggestFoundations(db, opts) {
+  const minSimilarity = opts.minSimilarity ?? 0.45;
+  const maxSimilarity = opts.maxSimilarity ?? 0.85;
+  const limit = opts.limit ?? 5;
+  const targetBloomLevel = opts.targetBloomLevel ?? 5;
+  if (minSimilarity >= maxSimilarity) {
+    return [];
+  }
+  const embedded = await listEmbeddedTokens(db, opts.model);
+  if (embedded.length === 0) {
+    return [];
+  }
+  const queryVec = Float32Array.from(opts.queryEmbedding);
+  const candidates = [];
+  for (const row of embedded) {
+    if (opts.targetTokenId && row.token.id === opts.targetTokenId) {
+      continue;
+    }
+    const similarity = cosineSimilarity(queryVec, row.embedding);
+    if (similarity >= minSimilarity && similarity < maxSimilarity) {
+      candidates.push({ token: row.token, similarity });
+    }
+  }
+  candidates.sort((a, b) => {
+    if (Math.abs(a.similarity - b.similarity) > 1e-9) {
+      return b.similarity - a.similarity;
+    }
+    return a.token.slug.localeCompare(b.token.slug);
+  });
+  const topCandidates = candidates.slice(0, limit);
+  const prereqIds = /* @__PURE__ */ new Set();
+  let ancestors;
+  if (opts.targetTokenId) {
+    const prereqs = await getPrerequisites(db, opts.targetTokenId);
+    for (const p of prereqs) {
+      prereqIds.add(p.requires_id);
+    }
+    ancestors = await buildAncestorMap(db);
+  }
+  const results = [];
+  for (const cand of topCandidates) {
+    let alreadyPrerequisite = false;
+    let wouldCreateCycleFlag = false;
+    const bloomAboveTarget = cand.token.bloom_level > targetBloomLevel;
+    if (opts.targetTokenId) {
+      alreadyPrerequisite = prereqIds.has(cand.token.id);
+      wouldCreateCycleFlag = await wouldCreateCycle(
+        db,
+        opts.targetTokenId,
+        cand.token.id,
+        ancestors
+      );
+    }
+    results.push({
+      token: cand.token,
+      similarity: cand.similarity,
+      alreadyPrerequisite,
+      wouldCreateCycle: wouldCreateCycleFlag,
+      bloomAboveTarget
+    });
+  }
+  return results;
+}
+
 // src/kernel/system/hooks.ts
 import {
   appendFileSync as appendFileSync3,
@@ -10559,9 +10624,7 @@ async function findPossibleDuplicates(db, candidate, embed = embedQuery) {
       );
     }
   }
-  const thresholdStr = await getSetting(db, "search.dedup_threshold");
-  const parsed = thresholdStr ? Number.parseFloat(thresholdStr) : Number.NaN;
-  const threshold = Number.isFinite(parsed) && parsed > 0 && parsed <= 1 ? parsed : 0.85;
+  const threshold = await resolveDedupThreshold(db);
   const hits = await searchTokensHybrid(db, queryText, {
     queryEmbedding: q2.vector,
     model: q2.model,
@@ -10580,6 +10643,16 @@ async function findPossibleDuplicates(db, candidate, embed = embedQuery) {
   }
   return results;
 }
+async function resolveDedupThreshold(db) {
+  const thresholdStr = await getSetting(db, "search.dedup_threshold");
+  const parsed = thresholdStr ? Number.parseFloat(thresholdStr) : Number.NaN;
+  return Number.isFinite(parsed) && parsed > 0 && parsed <= 1 ? parsed : 0.85;
+}
+async function resolveSuggestMinSimilarity(db) {
+  const minStr = await getSetting(db, "search.suggest_min_similarity");
+  const parsed = minStr ? Number.parseFloat(minStr) : Number.NaN;
+  return Number.isFinite(parsed) && parsed > 0 && parsed <= 1 ? parsed : 0.45;
+}
 
 // src/cli/llm/vision.ts
 import { randomBytes } from "crypto";
@@ -12428,6 +12501,117 @@ bridgeCommand.command("relevant-tokens").description("Find tokens relevant to a
     });
   });
 });
+bridgeCommand.command("suggest-foundations").description("Propose existing tokens as foundation/prerequisite candidates").option("--user <id>", "User ID (default: whoami)").action(async (_opts) => {
+  await withDb2(async (db) => {
+    let raw;
+    if (isServeMode) {
+      raw = serveStdinPayload ?? "";
+    } else {
+      const chunks = [];
+      for await (const chunk of process.stdin) {
+        chunks.push(chunk);
+      }
+      raw = Buffer.concat(chunks).toString("utf-8").trim();
+    }
+    if (!raw) {
+      jsonError("No input received on stdin. Pipe JSON.");
+    }
+    let data;
+    try {
+      data = JSON.parse(raw);
+    } catch {
+      jsonError("Invalid JSON input");
+    }
+    let queryText = "";
+    let targetTokenId;
+    let targetBloomLevel;
+    let targetJson = null;
+    if (data?.slug !== void 0) {
+      if (typeof data.slug !== "string" || data.slug.trim() === "") {
+        jsonError("Invalid slug");
+      }
+      const token = await getTokenBySlug(db, data.slug);
+      if (!token) {
+        jsonError(`Token not found: ${data.slug}`);
+      }
+      queryText = embeddingContentForToken(token);
+      targetTokenId = token.id;
+      targetBloomLevel = token.bloom_level;
+      targetJson = { slug: token.slug };
+    } else {
+      if (!data?.concept || typeof data.concept !== "string" || data.concept.trim() === "") {
+        jsonError("JSON must include a non-empty 'slug' or 'concept' field");
+      }
+      queryText = embeddingContentForToken({
+        concept: data.concept,
+        question: typeof data.question === "string" ? data.question : null,
+        domain: typeof data.domain === "string" ? data.domain : ""
+      });
+      if (data.bloom_level !== void 0) {
+        if (typeof data.bloom_level !== "number" || !Number.isInteger(data.bloom_level) || data.bloom_level < 1 || data.bloom_level > 5) {
+          jsonError("bloom_level must be an integer between 1 and 5");
+        }
+        targetBloomLevel = data.bloom_level;
+      }
+    }
+    let limit = data?.limit ?? 5;
+    if (typeof limit !== "number" || limit <= 0 || !Number.isInteger(limit)) {
+      limit = 5;
+    }
+    if (limit > 20) {
+      limit = 20;
+    }
+    const q2 = await embedQuery(db, queryText);
+    if (q2 === null) {
+      jsonOut2({
+        semantic: false,
+        target: targetJson,
+        suggestions: []
+      });
+      return;
+    }
+    try {
+      await ensureTokenEmbeddings(db, {
+        limit: 100,
+        dims: q2.vector.length
+      });
+    } catch {
+    }
+    const maxSimilarity = await resolveDedupThreshold(db);
+    const minSimilarity = await resolveSuggestMinSimilarity(db);
+    if (minSimilarity >= maxSimilarity) {
+      jsonOut2({
+        semantic: true,
+        target: targetJson,
+        suggestions: []
+      });
+      return;
+    }
+    const suggestions = await suggestFoundations(db, {
+      queryEmbedding: q2.vector,
+      model: q2.model,
+      targetTokenId,
+      targetBloomLevel,
+      limit,
+      minSimilarity,
+      maxSimilarity
+    });
+    jsonOut2({
+      semantic: true,
+      target: targetJson,
+      suggestions: suggestions.map((s) => ({
+        slug: s.token.slug,
+        concept: s.token.concept,
+        domain: s.token.domain,
+        bloom_level: s.token.bloom_level,
+        similarity: s.similarity,
+        already_prerequisite: s.alreadyPrerequisite,
+        would_create_cycle: s.wouldCreateCycle,
+        bloom_above_target: s.bloomAboveTarget
+      }))
+    });
+  });
+});
 bridgeCommand.command("discover-skills").description(
   "Analyze monitor logs across sessions to discover recurring patterns"
 ).option(
@@ -17452,6 +17636,46 @@ WARNING: Possible duplicate tokens found:`);
           );
         }
       }
+      try {
+        const queryText = embeddingContentForToken({
+          concept: opts.concept,
+          question: question ?? null,
+          domain: opts.domain ?? ""
+        });
+        const q2 = await embedQuery(db, queryText);
+        if (q2) {
+          const maxSimilarity = await resolveDedupThreshold(db);
+          const minSimilarity = await resolveSuggestMinSimilarity(db);
+          const suggestions = await suggestFoundations(db, {
+            queryEmbedding: q2.vector,
+            model: q2.model,
+            targetTokenId: token.id,
+            targetBloomLevel: Number(opts.bloom),
+            limit: 3,
+            minSimilarity,
+            maxSimilarity
+          });
+          const filtered = suggestions.filter(
+            (s) => !s.wouldCreateCycle && !s.alreadyPrerequisite
+          );
+          if (filtered.length > 0) {
+            console.log(
+              `
+Related existing tokens as potential foundations:`
+            );
+            for (const s of filtered) {
+              const note = s.bloomAboveTarget ? " (higher bloom than target)" : "";
+              console.log(
+                `  - ${s.token.slug} (similarity: ${s.similarity.toFixed(2)})${note}`
+              );
+            }
+            console.log(
+              `Link with: zam token prereq --token <slug> --requires <slug> (see zam token prereq --help)`
+            );
+          }
+        }
+      } catch {
+      }
     }
   });
 });