@almadar/workspace 0.1.2 → 0.1.4

package/dist/__tests__/concurrent-resolve.test.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Regression test for the per-(userId, appId) `openWorkspace` dedupe.
+ *
+ * Two concurrent calls with the same appId both run
+ * `findLocalWorkspaceDir` before either has written `app-marker.json`;
+ * without the in-flight Promise cache they both fall through to
+ * `mintSessionDir` and produce two distinct workspaces for the same
+ * logical app. The cache makes them share the first call's resolved
+ * service.
+ *
+ * Anonymous calls (no appId) must NOT dedupe — each anonymous mint is
+ * an independent session.
+ */
+export {};

package/dist/__tests__/mint-collision.test.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Regression test for the `mintSessionDir` same-millisecond collision.
+ *
+ * Before the fix: `mintSessionDir` used `Date.now().toString(36)` alone
+ * as the dir suffix. Two concurrent mints in the same millisecond
+ * produced the same path; the subsequent `backend.mkdir(..., { recursive:
+ * true })` silently succeeded for both, and two `WorkspaceService`
+ * instances ended up pointing at the same directory.
+ *
+ * After the fix: the suffix appends 4 hex chars of `randomBytes(2)` so
+ * concurrent mints produce distinct paths even within the same ms.
+ *
+ * The test fires 50 anonymous (no appId) mints concurrently and asserts
+ * every `workDir` is unique. Without the random tail the assertion fails
+ * deterministically on a multi-core box; with the fix it passes.
+ */
+export {};

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.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,6 +1,8 @@
 import path2 from 'path';
 import fs from 'fs';
 import { execFile } from 'child_process';
+import { randomBytes, createHash } from 'crypto';
+import { EmbeddingClient } from '@almadar/llm';
 
 // src/open-workspace.ts
 var LocalBackend = class {
@@ -502,7 +504,7 @@ async function findLocalWorkspaceDir(backend, workspacesRoot, userId, appId) {
 }
 function mintSessionDir(workspacesRoot, userId) {
   const ts = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
-  const suffix = Date.now().toString(36);
+  const suffix = `${Date.now().toString(36)}${randomBytes(2).toString("hex")}`;
   return path2.join(workspacesRoot, userId, `${ts}_${suffix}`);
 }
 async function restoreWorkspace(backend, rootDir, restore) {
@@ -528,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));
 }
@@ -537,6 +548,278 @@ 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"]);
+  }
+  pushString(segments, spec["organism"]);
+  const traitNames = extractTraitNamesFromSpec(spec);
+  if (traitNames.length > 0) {
+    segments.push(traitNames.join(", "));
+  }
+  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;
+}
+function extractTraitNamesFromSpec(spec) {
+  const out = [];
+  const params = asJsonObject(spec["params"]);
+  if (!params) return out;
+  const traitOverrides = asJsonObject(params["traitOverrides"]);
+  if (traitOverrides) {
+    for (const key of Object.keys(traitOverrides).sort()) out.push(key);
+  }
+  const extras = params["extraTraits"];
+  if (Array.isArray(extras)) {
+    for (const entry of extras) {
+      const obj = asJsonObject(entry);
+      if (!obj) continue;
+      const alias = typeof obj["name"] === "string" && obj["name"].length > 0 ? obj["name"] : typeof obj["ref"] === "string" ? tailOfRef(obj["ref"]) : null;
+      if (alias) out.push(alias);
+    }
+  }
+  return out;
+}
+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",
@@ -562,6 +845,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() {
@@ -1008,9 +1299,47 @@ 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();
+function openWorkspaceCacheKey(opts) {
+  if (opts.appId === void 0) return null;
+  const backendTag = opts.backend === "memory" ? "memory" : "local";
+  return `${backendTag}:${opts.userId}:${opts.appId}`;
+}
 async function openWorkspace(opts) {
+  const key = openWorkspaceCacheKey(opts);
+  if (key !== null) {
+    const cached = openWorkspaceInFlight.get(key);
+    if (cached) return cached;
+    const pending = (async () => {
+      try {
+        return await openWorkspaceInternal(opts);
+      } catch (err) {
+        openWorkspaceInFlight.delete(key);
+        throw err;
+      }
+    })();
+    openWorkspaceInFlight.set(key, pending);
+    return pending;
+  }
+  return openWorkspaceInternal(opts);
+}
+async function openWorkspaceInternal(opts) {
   const backend = opts.backend === "memory" ? new MemoryBackend() : new LocalBackend();
   const sinks = new SinkManager();
   const resolved = await resolveLifecycle(backend, opts);
@@ -1038,14 +1367,17 @@ async function openWorkspace(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) {
@@ -1077,6 +1409,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