@almadar/workspace 0.1.3 → 0.1.5

package/dist/__tests__/workspace-index-cosine.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/workspace-index-fingerprint.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/workspace-index-real-embedder.test.d.ts

@@ -0,0 +1,14 @@
+/**
+ * End-to-end retrieval spec on the REAL `@almadar/llm` EmbeddingClient
+ * (bge-base-en-v1.5, 768-d). Skipped automatically when
+ * `OPEN_ROUTER_API_KEY` is not set in the environment.
+ *
+ * Purpose: validate before consumer integration that the workspace
+ * index actually catches the R-10 (orbital name drift) and R-8
+ * (extraTraits[] duplicate-ref) failure modes the design doc targets.
+ * Mock-embedder tests prove the wiring; this spec proves the geometry.
+ *
+ * Also reports per-fixture cosine to confirm
+ * `DEFAULT_COERCION_THRESHOLD = 0.85` is in the right ballpark.
+ */
+export {};

package/dist/__tests__/workspace-index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -8,3 +8,5 @@
  */
 export { openWorkspace } from './open-workspace.js';
 export type { WorkspaceService, WorkspaceObserver, WorkspaceWriteEvent, OpenWorkspaceOptions, RestoreBackend, GitHubConfig, GitStatusInfo, FileTreeNode, } from './types.js';
+export type { WorkspaceIndex, EmbedderPort, ResolveResult, ResolveOptions, TraitRefEmit, WorkspaceIndexStats, OrbitalIndexEntry, ExtraTraitIdentity, } from './workspace-index/types.js';
+export { DEFAULT_COERCION_THRESHOLD, WORKSPACE_INDEX_SCHEMA_VERSION, } from './workspace-index/types.js';

package/dist/index.js

@@ -1,7 +1,8 @@
 import path2 from 'path';
 import fs from 'fs';
 import { execFile } from 'child_process';
-import { randomBytes } from 'crypto';
+import { randomBytes, createHash } from 'crypto';
+import { EmbeddingClient } from '@almadar/llm';
 
 // src/open-workspace.ts
 var LocalBackend = class {
@@ -529,6 +530,15 @@ async function restoreWorkspace(backend, rootDir, restore) {
 }
 
 // src/internal/memory-files.ts
+async function readJsonFile(backend, absPath) {
+  if (!backend.exists(absPath)) return null;
+  try {
+    const raw = await backend.readFile(absPath);
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
 async function writeJsonFile(backend, absPath, value) {
   await backend.writeFile(absPath, JSON.stringify(value, null, 2));
 }
@@ -538,6 +548,254 @@ async function appendJsonLine(backend, absPath, value) {
   await backend.writeFile(absPath, existing + ending + JSON.stringify(value) + "\n");
 }
 
+// src/workspace-index/types.ts
+var WORKSPACE_INDEX_SCHEMA_VERSION = 1;
+var DEFAULT_COERCION_THRESHOLD = 0.85;
+
+// src/workspace-index/cosine.ts
+function cosineSimilarity(a, b) {
+  if (a.length !== b.length || a.length === 0) return 0;
+  let dot = 0;
+  let magA = 0;
+  let magB = 0;
+  for (let i = 0; i < a.length; i++) {
+    const av = a[i] ?? 0;
+    const bv = b[i] ?? 0;
+    dot += av * bv;
+    magA += av * av;
+    magB += bv * bv;
+  }
+  if (magA === 0 || magB === 0) return 0;
+  return dot / (Math.sqrt(magA) * Math.sqrt(magB));
+}
+
+// src/workspace-index/fingerprint.ts
+function composeOrbitalIdentityFingerprint(spec) {
+  const segments = [];
+  pushString(segments, spec["orbitalName"]);
+  const params = asJsonObject(spec["params"]);
+  if (params) {
+    pushString(segments, params["entityName"]);
+  }
+  return segments.join(" \xB7 ");
+}
+function composeExtraTraitIdentityFingerprint(emit) {
+  const segments = [];
+  pushString(segments, emit.ref);
+  const alias = emit.name && emit.name.length > 0 ? emit.name : tailOfRef(emit.ref);
+  if (alias && alias !== emit.ref) {
+    pushString(segments, alias);
+  }
+  pushString(segments, emit.linkedEntity);
+  return segments.join(" \xB7 ");
+}
+function deriveExtraTraitAlias(emit) {
+  if (emit.name && emit.name.length > 0) return emit.name;
+  return tailOfRef(emit.ref);
+}
+function pushString(out, value) {
+  if (typeof value === "string" && value.length > 0) out.push(value);
+}
+function asJsonObject(value) {
+  if (value === void 0 || value === null) return null;
+  if (typeof value !== "object" || Array.isArray(value)) return null;
+  return value;
+}
+function tailOfRef(ref) {
+  const match = /\.traits\.([A-Za-z0-9_]+)$/.exec(ref);
+  return match ? match[1] : ref;
+}
+var SIDECAR_BASENAME = "index.json";
+function sidecarPath(workDir, orbital) {
+  return orbitalSessionFile(workDir, orbital, SIDECAR_BASENAME);
+}
+async function readSidecar(backend, workDir, orbital) {
+  const raw = await readJsonFile(backend, sidecarPath(workDir, orbital));
+  if (raw === null) return null;
+  if (raw.schemaVersion !== WORKSPACE_INDEX_SCHEMA_VERSION) return null;
+  return raw;
+}
+async function writeSidecar(backend, workDir, orbital, entry) {
+  await ensureOrbitalSessionDir(backend, workDir, orbital);
+  await writeJsonFile(
+    backend,
+    sidecarPath(workDir, orbital),
+    entry
+  );
+}
+function checksumSpec(spec) {
+  return createHash("sha256").update(JSON.stringify(spec)).digest("hex");
+}
+
+// src/workspace-index/index-impl.ts
+var WorkspaceIndexImpl = class {
+  constructor(deps) {
+    this.deps = deps;
+    this.entries = /* @__PURE__ */ new Map();
+    /** Serialized re-bake per orbital so concurrent writeSpec events don't race. */
+    this.bakeQueue = /* @__PURE__ */ new Map();
+    /** Names whose checksum doesn't match the current spec — surfaced via stats. */
+    this.stale = /* @__PURE__ */ new Set();
+    this.deps.sinks.subscribe({
+      onWrite: async (event) => {
+        if (event.kind !== "spec") return;
+        await this.rebakeOrbital(event.orbital, event.content);
+      }
+    });
+  }
+  async warm() {
+    const orbitals = this.deps.listOrbitals();
+    const work = [];
+    for (const orbital of orbitals) {
+      const spec = this.deps.readSpec(orbital);
+      if (spec === null) {
+        continue;
+      }
+      const checksum = checksumSpec(spec);
+      const existing = await readSidecar(this.deps.backend, this.deps.workDir, orbital);
+      if (existing !== null && existing.specChecksum === checksum) {
+        this.entries.set(orbital, existing);
+        this.stale.delete(orbital);
+        continue;
+      }
+      work.push(this.bakeAndPersist(orbital, spec, checksum));
+    }
+    await Promise.all(work);
+  }
+  async resolveOrbitalName(name, opts) {
+    const threshold = opts?.threshold ?? DEFAULT_COERCION_THRESHOLD;
+    if (this.entries.size === 0) {
+      return { coercedTo: null, similarity: 0, method: "identity-vector" };
+    }
+    const [vector] = await this.embedOne(name);
+    let bestOrbital = null;
+    let bestSim = 0;
+    for (const [orbital, entry] of this.entries) {
+      const sim = cosineSimilarity(vector, entry.identityVector);
+      if (sim > bestSim) {
+        bestSim = sim;
+        bestOrbital = orbital;
+      }
+    }
+    if (bestOrbital !== null && bestSim >= threshold) {
+      return { coercedTo: bestOrbital, similarity: bestSim, method: "identity-vector" };
+    }
+    return { coercedTo: null, similarity: bestSim, method: "identity-vector" };
+  }
+  async resolveTraitRef(emit, orbitalContext, opts) {
+    const threshold = opts?.threshold ?? DEFAULT_COERCION_THRESHOLD;
+    const entry = this.entries.get(orbitalContext.orbitalName);
+    if (!entry || entry.extraTraitIdentities.length === 0) {
+      return { coercedTo: null, similarity: 0, method: "identity-vector" };
+    }
+    const fingerprint = composeExtraTraitIdentityFingerprint(emit);
+    const [vector] = await this.embedOne(fingerprint);
+    let bestAlias = null;
+    let bestSim = 0;
+    for (const candidate of entry.extraTraitIdentities) {
+      const sim = cosineSimilarity(vector, candidate.vector);
+      if (sim > bestSim) {
+        bestSim = sim;
+        bestAlias = candidate.alias;
+      }
+    }
+    if (bestAlias !== null && bestSim >= threshold) {
+      return { coercedTo: bestAlias, similarity: bestSim, method: "identity-vector" };
+    }
+    return { coercedTo: null, similarity: bestSim, method: "identity-vector" };
+  }
+  stats() {
+    let extraTraitIdentityCount = 0;
+    for (const entry of this.entries.values()) {
+      extraTraitIdentityCount += entry.extraTraitIdentities.length;
+    }
+    return {
+      orbitalCount: this.entries.size,
+      extraTraitIdentityCount,
+      staleOrbitals: Array.from(this.stale).sort()
+    };
+  }
+  async rebakeOrbital(orbital, spec) {
+    const checksum = checksumSpec(spec);
+    const existing = this.entries.get(orbital);
+    if (existing && existing.specChecksum === checksum) return;
+    await this.enqueueBake(orbital, () => this.bakeAndPersist(orbital, spec, checksum));
+  }
+  enqueueBake(orbital, op) {
+    const prev = this.bakeQueue.get(orbital) ?? Promise.resolve();
+    const next = prev.then(op);
+    const swallowed = next.catch(() => void 0);
+    this.bakeQueue.set(orbital, swallowed);
+    return next;
+  }
+  async bakeAndPersist(orbital, spec, checksum) {
+    this.stale.add(orbital);
+    const identityFingerprint = composeOrbitalIdentityFingerprint(spec);
+    const extraInputs = extractExtraTraitInputs(spec);
+    const allTexts = [identityFingerprint, ...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 extraTraitIdentities = extraInputs.map((input, idx) => ({
+      ref: input.ref,
+      alias: input.alias,
+      fingerprint: input.fingerprint,
+      vector: extraVectors[idx]
+    }));
+    const entry = {
+      schemaVersion: WORKSPACE_INDEX_SCHEMA_VERSION,
+      specChecksum: checksum,
+      identityVector,
+      identityFingerprint,
+      extraTraitIdentities,
+      bakedAt: Date.now()
+    };
+    await writeSidecar(this.deps.backend, this.deps.workDir, orbital, entry);
+    this.entries.set(orbital, entry);
+    this.stale.delete(orbital);
+  }
+  async embedOne(text) {
+    const { embeddings } = await this.deps.embedder.embedBatch([text]);
+    if (embeddings.length !== 1) {
+      throw new Error(
+        `[workspace-index] embedder returned ${embeddings.length} vectors for a single text`
+      );
+    }
+    return embeddings;
+  }
+};
+function extractExtraTraitInputs(spec) {
+  const params = asJsonObject2(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);
+    if (!obj) continue;
+    const ref = typeof obj["ref"] === "string" ? obj["ref"] : null;
+    if (ref === null) continue;
+    const name = typeof obj["name"] === "string" ? obj["name"] : void 0;
+    const linkedEntity = typeof obj["linkedEntity"] === "string" ? obj["linkedEntity"] : void 0;
+    const alias = deriveExtraTraitAlias({ ref, name });
+    out.push({
+      ref,
+      alias,
+      fingerprint: composeExtraTraitIdentityFingerprint({ ref, name, linkedEntity })
+    });
+  }
+  return out;
+}
+function asJsonObject2(value) {
+  if (value === void 0 || value === null) return null;
+  if (typeof value !== "object" || Array.isArray(value)) return null;
+  return value;
+}
+
 // src/service.ts
 var COORD_FILES = {
   analysis: "analysis.json",
@@ -563,6 +821,14 @@ var WorkspaceServiceImpl = class {
     this._appId = args.appId;
     this.git = args.git;
     this.github = args.github;
+    this.index = new WorkspaceIndexImpl({
+      workDir: this.workDir,
+      backend: this.backend,
+      sinks: this.sinks,
+      embedder: args.embedder,
+      listOrbitals: () => this.listOrbitals(),
+      readSpec: (orbital) => this.readSpec(orbital)
+    });
   }
   // === Identity ===
   get appId() {
@@ -1009,6 +1275,20 @@ async function removeTree(backend, dir) {
     }
   }
 }
+function createDefaultEmbedder() {
+  let client = null;
+  function get() {
+    if (client === null) client = new EmbeddingClient({ provider: "openrouter" });
+    return client;
+  }
+  return {
+    async embedBatch(texts) {
+      if (texts.length === 0) return { embeddings: [] };
+      const result = await get().embedBatch(texts);
+      return { embeddings: result.embeddings };
+    }
+  };
+}
 
 // src/open-workspace.ts
 var openWorkspaceInFlight = /* @__PURE__ */ new Map();
@@ -1063,14 +1343,17 @@ async function openWorkspaceInternal(opts) {
   if (opts.github && opts.backend !== "memory") {
     git = await ensureGitInit(backend, resolved.workDir);
   }
-  return new WorkspaceServiceImpl({
+  const service = new WorkspaceServiceImpl({
     workDir: resolved.workDir,
     backend,
     sinks,
+    embedder: opts.embedder ?? createDefaultEmbedder(),
     appId: resolved.appId,
     git,
     github: opts.github
   });
+  await service.index.warm();
+  return service;
 }
 async function resolveLifecycle(backend, opts) {
   if (opts.adopt) {
@@ -1102,6 +1385,6 @@ async function resolveLifecycle(backend, opts) {
   return { workDir, appId: opts.appId };
 }
 
-export { openWorkspace };
+export { DEFAULT_COERCION_THRESHOLD, WORKSPACE_INDEX_SCHEMA_VERSION, openWorkspace };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map