@almadar/workspace 0.1.6 → 0.2.0

package/dist/index.js

@@ -233,6 +233,9 @@ function compiledFile(workDir, relPath) {
 function appMarkerFile(workDir) {
   return path2.join(workDir, WORKSPACE_LAYOUT.APP_MARKER);
 }
+function workspaceIndexManifestFile(workDir) {
+  return path2.join(workDir, WORKSPACE_LAYOUT.ALMADAR_DIR, "index.json");
+}
 function sandboxedPath(workDir, relPath) {
   if (typeof relPath !== "string" || relPath.length === 0) {
     throw new Error("sandbox: empty relative path");
@@ -549,8 +552,10 @@ async function appendJsonLine(backend, absPath, value) {
 }
 
 // src/workspace-index/types.ts
-var WORKSPACE_INDEX_SCHEMA_VERSION = 1;
+var WORKSPACE_INDEX_SCHEMA_VERSION = 2;
 var DEFAULT_COERCION_THRESHOLD = 0.85;
+var RRF_K = 60;
+var DEFAULT_RETRIEVAL_TOP_K = 3;
 
 // src/workspace-index/cosine.ts
 function cosineSimilarity(a, b) {
@@ -593,6 +598,75 @@ function deriveExtraTraitAlias(emit) {
   if (emit.name && emit.name.length > 0) return emit.name;
   return tailOfRef(emit.ref);
 }
+function composeOrbitalContentFingerprint(spec) {
+  const segments = [composeOrbitalIdentityFingerprint(spec)];
+  const params = asJsonObject(spec["params"]);
+  if (params) {
+    const traitOverrides = asJsonObject(params["traitOverrides"]);
+    if (traitOverrides) {
+      for (const trait of Object.keys(traitOverrides).sort()) {
+        segments.push(trait);
+        const override = asJsonObject(traitOverrides[trait]);
+        if (!override) continue;
+        const config = asJsonObject(override["config"]);
+        if (!config) continue;
+        for (const knob of Object.keys(config).sort()) {
+          const rendered = renderKnobValue(config[knob]);
+          if (rendered.length > 0) segments.push(`${trait}.${knob}: ${rendered}`);
+        }
+      }
+    }
+    const fields = params["entityFields"];
+    if (Array.isArray(fields)) {
+      const names = [];
+      for (const f of fields) {
+        const obj = asJsonObject(f);
+        if (obj && typeof obj["name"] === "string") names.push(obj["name"]);
+      }
+      if (names.length > 0) segments.push(names.join(", "));
+    }
+    const extras = params["extraTraits"];
+    if (Array.isArray(extras)) {
+      const labels = [];
+      for (const e of extras) {
+        const obj = asJsonObject(e);
+        if (!obj) continue;
+        const ref = typeof obj["ref"] === "string" ? obj["ref"] : null;
+        const name = typeof obj["name"] === "string" ? obj["name"] : null;
+        const label = name && name.length > 0 ? name : ref ? tailOfRef(ref) : null;
+        if (label) labels.push(label);
+      }
+      if (labels.length > 0) segments.push(labels.join(", "));
+    }
+    const ruleOverlay = asJsonObject(params["ruleOverlay"]);
+    if (ruleOverlay) {
+      const rules = ruleOverlay["rules"];
+      if (Array.isArray(rules)) {
+        const caps = [];
+        for (const r of rules) {
+          const obj = asJsonObject(r);
+          if (obj && typeof obj["capability"] === "string") caps.push(obj["capability"]);
+        }
+        if (caps.length > 0) segments.push(caps.join(", "));
+      }
+    }
+  }
+  return segments.filter((s) => s.length > 0).join(" \xB7 ");
+}
+function renderKnobValue(value) {
+  if (value === void 0 || value === null) return "";
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  if (Array.isArray(value)) {
+    const parts = [];
+    for (const entry of value) {
+      if (typeof entry === "string") parts.push(entry);
+      else if (typeof entry === "number" || typeof entry === "boolean") parts.push(String(entry));
+    }
+    return parts.join(", ");
+  }
+  return "";
+}
 function pushString(out, value) {
   if (typeof value === "string" && value.length > 0) out.push(value);
 }
@@ -627,6 +701,392 @@ function checksumSpec(spec) {
   return createHash("sha256").update(JSON.stringify(spec)).digest("hex");
 }
 
+// src/workspace-index/bm25.ts
+function tokenizeSpec(spec) {
+  const tokens = [];
+  pushTokens(tokens, spec["orbitalName"]);
+  const params = asJsonObject2(spec["params"]);
+  if (params) {
+    pushTokens(tokens, params["entityName"]);
+    const fields = params["entityFields"];
+    if (Array.isArray(fields)) {
+      for (const f of fields) {
+        const obj = asJsonObject2(f);
+        if (obj) pushTokens(tokens, obj["name"]);
+      }
+    }
+    const extras = params["extraTraits"];
+    if (Array.isArray(extras)) {
+      for (const e of extras) {
+        const obj = asJsonObject2(e);
+        if (!obj) continue;
+        pushTokens(tokens, obj["name"]);
+        const ref = obj["ref"];
+        if (typeof ref === "string") {
+          pushTokens(tokens, tailOfRef2(ref));
+        }
+      }
+    }
+    const pages = params["pages"];
+    if (Array.isArray(pages)) {
+      for (const p of pages) {
+        const obj = asJsonObject2(p);
+        if (!obj) continue;
+        const path9 = obj["path"];
+        if (typeof path9 === "string") pushTokens(tokens, path9);
+      }
+    }
+    const ruleOverlay = asJsonObject2(params["ruleOverlay"]);
+    if (ruleOverlay) {
+      const rules = ruleOverlay["rules"];
+      if (Array.isArray(rules)) {
+        for (const r of rules) {
+          const obj = asJsonObject2(r);
+          if (obj) pushTokens(tokens, obj["capability"]);
+        }
+      }
+    }
+    const traitOverrides = asJsonObject2(params["traitOverrides"]);
+    if (traitOverrides) {
+      for (const trait of Object.keys(traitOverrides)) {
+        pushTokens(tokens, trait);
+        const override = asJsonObject2(traitOverrides[trait]);
+        if (!override) continue;
+        const config = asJsonObject2(override["config"]);
+        if (!config) continue;
+        for (const knob of Object.keys(config)) {
+          pushPrimitiveValue(tokens, config[knob]);
+        }
+      }
+    }
+  }
+  return tokens;
+}
+function buildBM25Table(tokensPerOrbital) {
+  const documents = {};
+  const docFreq = {};
+  let totalLen = 0;
+  const orbitals = Object.keys(tokensPerOrbital);
+  for (const orbital of orbitals) {
+    const list = tokensPerOrbital[orbital] ?? [];
+    const termFreq = {};
+    for (const t of list) {
+      termFreq[t] = (termFreq[t] ?? 0) + 1;
+    }
+    const docLen = list.length;
+    totalLen += docLen;
+    documents[orbital] = { orbital, termFreq, docLen };
+    for (const term of Object.keys(termFreq)) {
+      docFreq[term] = (docFreq[term] ?? 0) + 1;
+    }
+  }
+  const docCount = orbitals.length;
+  const avgDocLen = docCount > 0 ? totalLen / docCount : 0;
+  return { documents, docFreq, docCount, avgDocLen };
+}
+function queryBM25(table, query, opts) {
+  const k1 = opts?.k1 ?? 1.5;
+  const b = opts?.b ?? 0.75;
+  const queryTokensRaw = tokenize(query);
+  if (queryTokensRaw.length === 0) return [];
+  const uniqueQueryTokens = Array.from(new Set(queryTokensRaw));
+  const { documents, docFreq, docCount, avgDocLen } = table;
+  if (docCount === 0 || avgDocLen === 0) return [];
+  const results = [];
+  for (const orbital of Object.keys(documents)) {
+    const doc = documents[orbital];
+    if (!doc) continue;
+    let score = 0;
+    const matched = [];
+    for (const qt of uniqueQueryTokens) {
+      const tf = doc.termFreq[qt] ?? 0;
+      if (tf === 0) continue;
+      const df = docFreq[qt] ?? 0;
+      const idf = Math.log1p((docCount - df + 0.5) / (df + 0.5));
+      const norm = tf + k1 * (1 - b + b * doc.docLen / avgDocLen);
+      const contribution = idf * tf * (k1 + 1) / norm;
+      if (contribution > 0) {
+        score += contribution;
+        matched.push(qt);
+      }
+    }
+    if (score > 0) results.push({ orbital, score, matchedTokens: matched });
+  }
+  results.sort((a, b2) => b2.score - a.score);
+  return results;
+}
+function tokenize(text) {
+  if (text.length === 0) return [];
+  const out = [];
+  const pieces = text.split(/[\s_\-/.:]+/u);
+  for (const piece of pieces) {
+    if (piece.length === 0) continue;
+    const lower = piece.toLowerCase();
+    if (lower.length >= 2) out.push(lower);
+    const parts = splitCamel(piece);
+    if (parts.length > 1) {
+      for (const part of parts) {
+        const p = part.toLowerCase();
+        if (p.length >= 2) out.push(p);
+      }
+    }
+  }
+  return out;
+}
+function splitCamel(s) {
+  return s.split(/(?<=[a-z0-9])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])/u);
+}
+function pushTokens(out, value) {
+  if (typeof value !== "string" || value.length === 0) return;
+  for (const t of tokenize(value)) out.push(t);
+}
+function pushPrimitiveValue(out, value) {
+  if (value === void 0 || value === null) return;
+  if (typeof value === "string") {
+    for (const t of tokenize(value)) out.push(t);
+    return;
+  }
+  if (typeof value === "number" || typeof value === "boolean") {
+    for (const t of tokenize(String(value))) out.push(t);
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const entry of value) pushPrimitiveValue(out, entry);
+  }
+}
+function asJsonObject2(value) {
+  if (value === void 0 || value === null) return null;
+  if (typeof value !== "object" || Array.isArray(value)) return null;
+  return value;
+}
+function tailOfRef2(ref) {
+  const match = /\.traits\.([A-Za-z0-9_]+)$/.exec(ref);
+  return match ? match[1] : ref;
+}
+
+// src/workspace-index/rrf.ts
+function rrfFuse(rankings, k = RRF_K) {
+  if (rankings.length === 0) return [];
+  const order = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const ranking of rankings) {
+    for (const key of ranking) {
+      if (!seen.has(key)) {
+        seen.add(key);
+        order.push(key);
+      }
+    }
+  }
+  const ranksByKey = /* @__PURE__ */ new Map();
+  const scoreByKey = /* @__PURE__ */ new Map();
+  for (const key of order) {
+    ranksByKey.set(
+      key,
+      rankings.map(() => null)
+    );
+    scoreByKey.set(key, 0);
+  }
+  for (let i = 0; i < rankings.length; i++) {
+    const ranking = rankings[i];
+    if (!ranking) continue;
+    for (let j = 0; j < ranking.length; j++) {
+      const key = ranking[j];
+      if (key === void 0) continue;
+      const rank = j + 1;
+      const ranks = ranksByKey.get(key);
+      if (ranks) ranks[i] = rank;
+      scoreByKey.set(key, (scoreByKey.get(key) ?? 0) + 1 / (k + rank));
+    }
+  }
+  const indexed = order.map((key, idx) => ({
+    key,
+    idx,
+    score: scoreByKey.get(key) ?? 0,
+    ranks: ranksByKey.get(key) ?? []
+  }));
+  indexed.sort((a, b) => {
+    if (b.score !== a.score) return b.score - a.score;
+    return a.idx - b.idx;
+  });
+  return indexed.map(({ key, score, ranks }) => ({ key, score, ranks }));
+}
+
+// src/workspace-index/graph-builders.ts
+function buildIntentMaps(specs) {
+  const entityNameOverrides = {};
+  const traitRefImporters = {};
+  const ruleCapabilities = {};
+  const organism = {};
+  const orbitalNames = Object.keys(specs).sort();
+  for (const orbital of orbitalNames) {
+    const spec = specs[orbital];
+    if (!spec) continue;
+    const organismName = typeof spec["organism"] === "string" ? spec["organism"] : null;
+    if (organismName && organismName.length > 0) {
+      (organism[organismName] ?? (organism[organismName] = [])).push(orbital);
+    }
+    const params = asJsonObject3(spec["params"]);
+    if (!params) continue;
+    const defaultEntity = typeof params["entityName"] === "string" ? params["entityName"] : null;
+    const traitOverrides = asJsonObject3(params["traitOverrides"]);
+    if (traitOverrides) {
+      for (const trait of Object.keys(traitOverrides).sort()) {
+        const override = asJsonObject3(traitOverrides[trait]);
+        if (!override) continue;
+        const linked = override["linkedEntity"];
+        if (typeof linked === "string" && linked.length > 0) {
+          (entityNameOverrides[linked] ?? (entityNameOverrides[linked] = [])).push({
+            orbital,
+            trait,
+            source: "override"
+          });
+        }
+      }
+    }
+    const extras = params["extraTraits"];
+    if (Array.isArray(extras)) {
+      for (const e of extras) {
+        const obj = asJsonObject3(e);
+        if (!obj) continue;
+        const ref = obj["ref"];
+        if (typeof ref === "string" && ref.length > 0) {
+          (traitRefImporters[ref] ?? (traitRefImporters[ref] = [])).push(orbital);
+        }
+      }
+    }
+    const ruleOverlay = asJsonObject3(params["ruleOverlay"]);
+    if (ruleOverlay) {
+      const rules = ruleOverlay["rules"];
+      if (Array.isArray(rules)) {
+        for (const r of rules) {
+          const obj = asJsonObject3(r);
+          if (!obj) continue;
+          const capability = obj["capability"];
+          if (typeof capability !== "string" || capability.length === 0) continue;
+          const entityName = typeof obj["entityName"] === "string" && obj["entityName"].length > 0 ? obj["entityName"] : defaultEntity;
+          if (!entityName) continue;
+          (ruleCapabilities[capability] ?? (ruleCapabilities[capability] = [])).push({
+            orbital,
+            entityName,
+            capability
+          });
+        }
+      }
+    }
+  }
+  return { entityNameOverrides, traitRefImporters, ruleCapabilities, organism };
+}
+function buildComposedMaps(schemaOrbContent) {
+  if (schemaOrbContent === null) return { events: {}, entityNameComposed: {} };
+  let parsed;
+  try {
+    parsed = JSON.parse(schemaOrbContent);
+  } catch {
+    return { events: {}, entityNameComposed: {} };
+  }
+  const root = asJsonObject3(parsed);
+  if (!root) return { events: {}, entityNameComposed: {} };
+  const orbitals = root["orbitals"];
+  if (!Array.isArray(orbitals)) return { events: {}, entityNameComposed: {} };
+  const events = {};
+  const entityNameComposed = {};
+  for (const o of orbitals) {
+    const orbObj = asJsonObject3(o);
+    if (!orbObj) continue;
+    const orbitalName = typeof orbObj["name"] === "string" ? orbObj["name"] : null;
+    if (!orbitalName) continue;
+    const entity = asJsonObject3(orbObj["entity"]);
+    if (entity) {
+      const entityName = entity["name"];
+      if (typeof entityName === "string" && entityName.length > 0) {
+        (entityNameComposed[entityName] ?? (entityNameComposed[entityName] = [])).push({
+          orbital: orbitalName,
+          trait: "<orbital-entity>",
+          source: "composed"
+        });
+      }
+    }
+    const traits = orbObj["traits"];
+    if (!Array.isArray(traits)) continue;
+    for (const t of traits) {
+      const traitObj = asJsonObject3(t);
+      if (!traitObj) continue;
+      const traitName = typeof traitObj["name"] === "string" ? traitObj["name"] : null;
+      if (!traitName) continue;
+      const linked = traitObj["linkedEntity"];
+      if (typeof linked === "string" && linked.length > 0) {
+        (entityNameComposed[linked] ?? (entityNameComposed[linked] = [])).push({
+          orbital: orbitalName,
+          trait: traitName,
+          source: "composed"
+        });
+      }
+      const states = traitObj["states"];
+      if (!Array.isArray(states)) continue;
+      for (const s of states) {
+        const stateObj = asJsonObject3(s);
+        if (!stateObj) continue;
+        const stateName = typeof stateObj["name"] === "string" ? stateObj["name"] : void 0;
+        const transitions = stateObj["transitions"];
+        if (!Array.isArray(transitions)) continue;
+        for (const tr of transitions) {
+          const trObj = asJsonObject3(tr);
+          if (!trObj) continue;
+          const listenEvent = trObj["event"];
+          if (typeof listenEvent === "string" && listenEvent.length > 0) {
+            (events[listenEvent] ?? (events[listenEvent] = [])).push({
+              orbital: orbitalName,
+              trait: traitName,
+              state: stateName,
+              role: "listen"
+            });
+          }
+          const emit = asJsonObject3(trObj["emit"]);
+          if (emit) {
+            const emitEvent = emit["event"];
+            if (typeof emitEvent === "string" && emitEvent.length > 0) {
+              const scope = emit["scope"];
+              const scopeNarrowed = scope === "internal" || scope === "external" ? scope : void 0;
+              const edge = {
+                orbital: orbitalName,
+                trait: traitName,
+                state: stateName,
+                role: "emit",
+                ...scopeNarrowed ? { scope: scopeNarrowed } : {}
+              };
+              (events[emitEvent] ?? (events[emitEvent] = [])).push(edge);
+            }
+          }
+        }
+      }
+    }
+  }
+  return { events, entityNameComposed };
+}
+function asJsonObject3(value) {
+  if (value === void 0 || value === null) return null;
+  if (typeof value !== "object" || Array.isArray(value)) return null;
+  return value;
+}
+
+// src/workspace-index/manifest.ts
+function manifestPath(workDir) {
+  return workspaceIndexManifestFile(workDir);
+}
+async function readManifest(backend, workDir) {
+  const raw = await readJsonFile(backend, manifestPath(workDir));
+  if (raw === null) return null;
+  if (raw.schemaVersion !== WORKSPACE_INDEX_SCHEMA_VERSION) return null;
+  return raw;
+}
+async function writeManifest(backend, workDir, manifest) {
+  await writeJsonFile(
+    backend,
+    manifestPath(workDir),
+    manifest
+  );
+}
+
 // src/workspace-index/index-impl.ts
 var WorkspaceIndexImpl = class {
   constructor(deps) {
@@ -636,13 +1096,53 @@ var WorkspaceIndexImpl = class {
     this.bakeQueue = /* @__PURE__ */ new Map();
     /** Names whose checksum doesn't match the current spec — surfaced via stats. */
     this.stale = /* @__PURE__ */ new Set();
+    /** Cached spec.json per orbital so manifest rebuilds don't re-read disk. */
+    this.specsByOrbital = /* @__PURE__ */ new Map();
+    /** Tokenized BM25 rows per orbital — rebuilt incrementally. */
+    this.tokensByOrbital = /* @__PURE__ */ new Map();
+    /** Last-known recency timeline per orbital. */
+    this.recencyByOrbital = /* @__PURE__ */ new Map();
+    /** Latest manifest payload (BM25 + intent + composed + recency). */
+    this.manifest = emptyManifest();
+    /** Serialized manifest writes so concurrent observer fires don't race. */
+    this.manifestQueue = Promise.resolve();
     this.deps.sinks.subscribe({
-      onWrite: async (event) => {
-        if (event.kind !== "spec") return;
-        await this.rebakeOrbital(event.orbital, event.content);
-      }
+      onWrite: (event) => this.onWorkspaceWrite(event)
     });
   }
+  async onWorkspaceWrite(event) {
+    switch (event.kind) {
+      case "spec":
+        await this.rebakeOrbital(event.orbital, event.content);
+        this.specsByOrbital.set(event.orbital, event.content);
+        this.tokensByOrbital.set(event.orbital, tokenizeSpec(event.content));
+        await this.scheduleManifestRebuild();
+        return;
+      case "schema":
+        await this.scheduleManifestRebuild();
+        return;
+      case "params-history":
+        this.recencyByOrbital.set(event.orbital, deriveRecencyEntry(event.orbital, [event.row], this.recencyByOrbital.get(event.orbital)));
+        await this.scheduleManifestRebuild();
+        return;
+      case "orbital-archived":
+        this.entries.delete(event.name);
+        this.specsByOrbital.delete(event.name);
+        this.tokensByOrbital.delete(event.name);
+        this.recencyByOrbital.delete(event.name);
+        await this.scheduleManifestRebuild();
+        return;
+      case "orbital-renamed":
+        renameKey(this.entries, event.from, event.to);
+        renameKey(this.specsByOrbital, event.from, event.to);
+        renameKey(this.tokensByOrbital, event.from, event.to);
+        renameKey(this.recencyByOrbital, event.from, event.to);
+        await this.scheduleManifestRebuild();
+        return;
+      default:
+        return;
+    }
+  }
   async warm() {
     const orbitals = this.deps.listOrbitals();
     const work = [];
@@ -651,6 +1151,12 @@ var WorkspaceIndexImpl = class {
       if (spec === null) {
         continue;
       }
+      this.specsByOrbital.set(orbital, spec);
+      this.tokensByOrbital.set(orbital, tokenizeSpec(spec));
+      const history = this.deps.readHistory(orbital);
+      if (history.length > 0) {
+        this.recencyByOrbital.set(orbital, deriveRecencyEntry(orbital, history, void 0));
+      }
       const checksum = checksumSpec(spec);
       const existing = await readSidecar(this.deps.backend, this.deps.workDir, orbital);
       if (existing !== null && existing.specChecksum === checksum) {
@@ -661,6 +1167,12 @@ var WorkspaceIndexImpl = class {
       work.push(this.bakeAndPersist(orbital, spec, checksum));
     }
     await Promise.all(work);
+    const restored = await readManifest(this.deps.backend, this.deps.workDir);
+    if (restored !== null) {
+      this.manifest = restored;
+      this.hydrateRecencyFromManifest(restored);
+    }
+    await this.rebuildManifest();
   }
   async resolveOrbitalName(name, opts) {
     const threshold = opts?.threshold ?? DEFAULT_COERCION_THRESHOLD;
@@ -715,6 +1227,133 @@ var WorkspaceIndexImpl = class {
       staleOrbitals: Array.from(this.stale).sort()
     };
   }
+  // ── Phase B — RRF-hybrid retrieval ──────────────────────────────────────────
+  async retrieveOrbitalsForPrompt(prompt, opts) {
+    const topK = opts?.topK ?? DEFAULT_RETRIEVAL_TOP_K;
+    const rrfK = opts?.rrfK ?? RRF_K;
+    if (this.entries.size === 0) return [];
+    const sparseHits = queryBM25(this.manifest.bm25, prompt, opts?.bm25);
+    const sparseRanking = sparseHits.map((h) => h.orbital);
+    const matchedTokensByOrbital = /* @__PURE__ */ new Map();
+    for (const hit of sparseHits) matchedTokensByOrbital.set(hit.orbital, hit.matchedTokens);
+    const [promptVector] = await this.embedOne(prompt);
+    const dense = [];
+    for (const [orbital, entry] of this.entries) {
+      const sim = cosineSimilarity(promptVector, entry.contentVector);
+      if (sim > 0) dense.push({ orbital, sim });
+    }
+    dense.sort((a, b) => b.sim - a.sim);
+    const denseRanking = dense.map((d) => d.orbital);
+    const fused = rrfFuse([denseRanking, sparseRanking], rrfK);
+    return fused.slice(0, topK).map((entry) => ({
+      orbitalName: entry.key,
+      score: entry.score,
+      matchedTokens: matchedTokensByOrbital.get(entry.key) ?? [],
+      matchedKnobs: this.explainKnobMatches(entry.key, prompt),
+      rankByDense: entry.ranks[0] ?? null,
+      rankBySparse: entry.ranks[1] ?? null
+    }));
+  }
+  findByToken(query) {
+    const hits = queryBM25(this.manifest.bm25, query);
+    return hits.map((h) => h.orbital);
+  }
+  // ── Phase C — graph queries ────────────────────────────────────────────────
+  orbitalsListeningTo(event) {
+    return (this.manifest.composed.events[event] ?? []).filter((e) => e.role === "listen");
+  }
+  orbitalsEmitting(event) {
+    return (this.manifest.composed.events[event] ?? []).filter((e) => e.role === "emit");
+  }
+  orbitalsLinkedToEntity(entity) {
+    const composed = this.manifest.composed.entityNameComposed[entity] ?? [];
+    const override = this.manifest.intent.entityNameOverrides[entity] ?? [];
+    return [...composed, ...override];
+  }
+  extraTraitImporters(refPath) {
+    return this.manifest.intent.traitRefImporters[refPath] ?? [];
+  }
+  rulesAppliedTo(entity) {
+    const out = [];
+    for (const bindings of Object.values(this.manifest.intent.ruleCapabilities)) {
+      for (const b of bindings) if (b.entityName === entity) out.push(b);
+    }
+    return out;
+  }
+  recentlyEdited(opts) {
+    const withinTurns = opts?.withinTurns ?? 5;
+    const entries = [];
+    for (const [orbital, recency] of Object.entries(this.manifest.recency)) {
+      entries.push({ orbital, recencyTurn: recency.recencyTurn });
+    }
+    if (entries.length === 0) return [];
+    const maxTurn = entries.reduce((m, e) => e.recencyTurn > m ? e.recencyTurn : m, -Infinity);
+    entries.sort((a, b) => b.recencyTurn - a.recencyTurn);
+    return entries.filter((e) => e.recencyTurn > maxTurn - withinTurns).map((e) => e.orbital);
+  }
+  // ── Manifest internals ─────────────────────────────────────────────────────
+  scheduleManifestRebuild() {
+    const next = this.manifestQueue.then(() => this.rebuildManifest());
+    this.manifestQueue = next.catch(() => void 0);
+    return next;
+  }
+  async rebuildManifest() {
+    const tokensPerOrbital = {};
+    for (const [orbital, tokens] of this.tokensByOrbital) {
+      tokensPerOrbital[orbital] = tokens;
+    }
+    const specsPerOrbital = {};
+    for (const [orbital, spec] of this.specsByOrbital) {
+      specsPerOrbital[orbital] = spec;
+    }
+    const recency = {};
+    for (const [orbital, entry] of this.recencyByOrbital) {
+      recency[orbital] = entry;
+    }
+    const next = {
+      schemaVersion: WORKSPACE_INDEX_SCHEMA_VERSION,
+      bm25: buildBM25Table(tokensPerOrbital),
+      intent: buildIntentMaps(specsPerOrbital),
+      composed: buildComposedMaps(this.deps.readSchema()),
+      recency,
+      bakedAt: Date.now()
+    };
+    this.manifest = next;
+    await writeManifest(this.deps.backend, this.deps.workDir, next);
+    await this.deps.sinks.notifyAll({
+      kind: "workspace-index-manifest",
+      content: serializeManifestForMirror(next)
+    });
+  }
+  hydrateRecencyFromManifest(manifest) {
+    for (const [orbital, entry] of Object.entries(manifest.recency)) {
+      this.recencyByOrbital.set(orbital, entry);
+    }
+  }
+  explainKnobMatches(orbital, prompt) {
+    const spec = this.specsByOrbital.get(orbital);
+    if (!spec) return [];
+    const params = asJsonObject4(spec["params"]);
+    if (!params) return [];
+    const traitOverrides = asJsonObject4(params["traitOverrides"]);
+    if (!traitOverrides) return [];
+    const promptLower = prompt.toLowerCase();
+    const out = [];
+    for (const trait of Object.keys(traitOverrides).sort()) {
+      const override = asJsonObject4(traitOverrides[trait]);
+      if (!override) continue;
+      const config = asJsonObject4(override["config"]);
+      if (!config) continue;
+      for (const knob of Object.keys(config).sort()) {
+        const rendered = renderKnobValueForExplain(config[knob]);
+        if (rendered.length === 0) continue;
+        if (promptLower.includes(rendered.toLowerCase())) {
+          out.push(`${trait}.${knob}`);
+        }
+      }
+    }
+    return out;
+  }
   async rebakeOrbital(orbital, spec) {
     const checksum = checksumSpec(spec);
     const existing = this.entries.get(orbital);
@@ -731,15 +1370,20 @@ var WorkspaceIndexImpl = class {
   async bakeAndPersist(orbital, spec, checksum) {
     this.stale.add(orbital);
     const identityFingerprint = composeOrbitalIdentityFingerprint(spec);
+    const contentFingerprint = composeOrbitalContentFingerprint(spec);
     const extraInputs = extractExtraTraitInputs(spec);
-    const allTexts = [identityFingerprint, ...extraInputs.map((e) => e.fingerprint)];
+    const allTexts = [
+      identityFingerprint,
+      contentFingerprint,
+      ...extraInputs.map((e) => e.fingerprint)
+    ];
     const { embeddings } = await this.deps.embedder.embedBatch(allTexts);
     if (embeddings.length !== allTexts.length) {
       throw new Error(
         `[workspace-index] embedder returned ${embeddings.length} vectors for ${allTexts.length} inputs`
       );
     }
-    const [identityVector, ...extraVectors] = embeddings;
+    const [identityVector, contentVector, ...extraVectors] = embeddings;
     const extraTraitIdentities = extraInputs.map((input, idx) => ({
       ref: input.ref,
       alias: input.alias,
@@ -751,6 +1395,8 @@ var WorkspaceIndexImpl = class {
       specChecksum: checksum,
       identityVector,
       identityFingerprint,
+      contentVector,
+      contentFingerprint,
       extraTraitIdentities,
       bakedAt: Date.now()
     };
@@ -779,6 +1425,8 @@ function serializeEntryForMirror(entry) {
     specChecksum: entry.specChecksum,
     identityVector: [...entry.identityVector],
     identityFingerprint: entry.identityFingerprint,
+    contentVector: [...entry.contentVector],
+    contentFingerprint: entry.contentFingerprint,
     extraTraitIdentities: entry.extraTraitIdentities.map((e) => ({
       ref: e.ref,
       alias: e.alias,
@@ -789,13 +1437,13 @@ function serializeEntryForMirror(entry) {
   };
 }
 function extractExtraTraitInputs(spec) {
-  const params = asJsonObject2(spec["params"]);
+  const params = asJsonObject4(spec["params"]);
   if (!params) return [];
   const extras = params["extraTraits"];
   if (!Array.isArray(extras)) return [];
   const out = [];
   for (const entry of extras) {
-    const obj = asJsonObject2(entry);
+    const obj = asJsonObject4(entry);
     if (!obj) continue;
     const ref = typeof obj["ref"] === "string" ? obj["ref"] : null;
     if (ref === null) continue;
@@ -810,11 +1458,102 @@ function extractExtraTraitInputs(spec) {
   }
   return out;
 }
-function asJsonObject2(value) {
+function asJsonObject4(value) {
   if (value === void 0 || value === null) return null;
   if (typeof value !== "object" || Array.isArray(value)) return null;
   return value;
 }
+function emptyManifest() {
+  return {
+    schemaVersion: WORKSPACE_INDEX_SCHEMA_VERSION,
+    bm25: { documents: {}, docFreq: {}, docCount: 0, avgDocLen: 0 },
+    intent: { entityNameOverrides: {}, traitRefImporters: {}, ruleCapabilities: {}, organism: {} },
+    composed: { events: {}, entityNameComposed: {} },
+    recency: {},
+    bakedAt: 0
+  };
+}
+function deriveRecencyEntry(_orbital, rows, prior) {
+  let recencyTurn = prior?.recencyTurn ?? 0;
+  let lastChange = prior?.lastChange ?? 0;
+  for (let i = 0; i < rows.length; i++) {
+    const row = rows[i];
+    const turn = typeof row["turn"] === "number" ? row["turn"] : recencyTurn + 1;
+    const ts = typeof row["timestamp"] === "number" ? row["timestamp"] : 0;
+    if (turn > recencyTurn) recencyTurn = turn;
+    if (ts > lastChange) lastChange = ts;
+  }
+  return { recencyTurn, lastChange };
+}
+function renameKey(map, from, to) {
+  if (!map.has(from)) return;
+  const value = map.get(from);
+  if (value === void 0) return;
+  map.delete(from);
+  map.set(to, value);
+}
+function renderKnobValueForExplain(value) {
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  return "";
+}
+function serializeManifestForMirror(manifest) {
+  return {
+    schemaVersion: manifest.schemaVersion,
+    bm25: serializeBM25(manifest.bm25),
+    intent: serializeIntent(manifest.intent),
+    composed: serializeComposed(manifest.composed),
+    recency: serializeRecency(manifest.recency),
+    bakedAt: manifest.bakedAt
+  };
+}
+function serializeBM25(t) {
+  const documents = {};
+  for (const [orbital, doc] of Object.entries(t.documents)) {
+    documents[orbital] = serializeBM25Doc(doc);
+  }
+  return {
+    documents,
+    docFreq: { ...t.docFreq },
+    docCount: t.docCount,
+    avgDocLen: t.avgDocLen
+  };
+}
+function serializeBM25Doc(doc) {
+  return {
+    orbital: doc.orbital,
+    termFreq: { ...doc.termFreq },
+    docLen: doc.docLen
+  };
+}
+function serializeIntent(intent) {
+  return {
+    entityNameOverrides: serializeMapOfArrays(intent.entityNameOverrides, (b) => ({ ...b })),
+    traitRefImporters: serializeMapOfArrays(intent.traitRefImporters, (s) => s),
+    ruleCapabilities: serializeMapOfArrays(intent.ruleCapabilities, (b) => ({ ...b })),
+    organism: serializeMapOfArrays(intent.organism, (s) => s)
+  };
+}
+function serializeComposed(composed) {
+  return {
+    events: serializeMapOfArrays(composed.events, (e) => ({ ...e })),
+    entityNameComposed: serializeMapOfArrays(composed.entityNameComposed, (b) => ({ ...b }))
+  };
+}
+function serializeRecency(recency) {
+  const out = {};
+  for (const [orbital, entry] of Object.entries(recency)) {
+    out[orbital] = { recencyTurn: entry.recencyTurn, lastChange: entry.lastChange };
+  }
+  return out;
+}
+function serializeMapOfArrays(map, projectOne) {
+  const out = {};
+  for (const [key, items] of Object.entries(map)) {
+    out[key] = items.map(projectOne);
+  }
+  return out;
+}
 
 // src/service.ts
 var COORD_FILES = {
@@ -847,7 +1586,9 @@ var WorkspaceServiceImpl = class {
       sinks: this.sinks,
       embedder: args.embedder,
       listOrbitals: () => this.listOrbitals(),
-      readSpec: (orbital) => this.readSpec(orbital)
+      readSpec: (orbital) => this.readSpec(orbital),
+      readSchema: () => this.readSchema(),
+      readHistory: (orbital) => this.readHistory(orbital)
     });
   }
   // === Identity ===
@@ -1405,6 +2146,6 @@ async function resolveLifecycle(backend, opts) {
   return { workDir, appId: opts.appId };
 }
 
-export { DEFAULT_COERCION_THRESHOLD, WORKSPACE_INDEX_SCHEMA_VERSION, openWorkspace };
+export { DEFAULT_COERCION_THRESHOLD, DEFAULT_RETRIEVAL_TOP_K, RRF_K, WORKSPACE_INDEX_SCHEMA_VERSION, openWorkspace };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map