@almadar/workspace 0.11.4 → 0.11.6

package/dist/__tests__/append-json-line.test.d.ts

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

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

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

package/dist/index.d.ts

@@ -10,6 +10,7 @@ export { openWorkspace } from './open-workspace.js';
 export { listWorkspaces } from './list-workspaces.js';
 export { deleteWorkspace } from './delete-workspace.js';
 export { openAccount } from './account.js';
-export type { WorkspaceService, InstantiateWorkspaceSeed, WorkspaceObserver, WorkspaceWriteEvent, WorkspaceWatchEvent, OpenWorkspaceOptions, ListWorkspacesOptions, WorkspaceSummary, RestoreBackend, GitHubConfig, GitStatusInfo, SnapshotMeta, WorkspaceArchiveBackend, FileTreeNode, AccountService, AccountConfig, ProviderCredential, AuthToken, AccountIdentity, OpenAccountOptions, } from './types.js';
-export type { WorkspaceIndex, EmbedderPort, ResolveResult, ResolveOptions, TraitRefEmit, WorkspaceIndexStats, OrbitalIndexEntry, ExtraTraitIdentity, RetrievalResult, RetrievalOptions, RecentlyEditedOptions, EventEdge, EntityBinding, RuleBinding, RecencyEntry, IntentMaps, ComposedMaps, BM25Document, BM25Table, BM25Options, WorkspaceIndexManifest, } from './workspace-index/types.js';
-export { DEFAULT_COERCION_THRESHOLD, DEFAULT_RETRIEVAL_TOP_K, RRF_K, WORKSPACE_INDEX_SCHEMA_VERSION, } from './workspace-index/types.js';
+export type { WorkspaceService, InstantiateWorkspaceSeed, WorkspaceObserver, WorkspaceWriteEvent, WorkspaceWatchEvent, OpenWorkspaceOptions, MountEntry, ListWorkspacesOptions, WorkspaceSummary, RestoreBackend, GitHubConfig, GitStatusInfo, SnapshotMeta, WorkspaceArchiveBackend, FileTreeNode, AccountService, AccountConfig, ProviderCredential, AuthToken, AccountIdentity, OpenAccountOptions, } from './types.js';
+export type { WorkspaceIndex, EmbedderPort, WorkspaceIndexStats, OrbitalIndexEntry, ExtraTraitIdentity, RetrievalResult, RetrievalOptions, RecentlyEditedOptions, EventEdge, EntityBinding, RuleBinding, RecencyEntry, IntentMaps, ComposedMaps, BM25Document, BM25Table, BM25Options, WorkspaceIndexManifest, } from './workspace-index/types.js';
+export { DEFAULT_RETRIEVAL_TOP_K, RRF_K, WORKSPACE_INDEX_SCHEMA_VERSION, } from './workspace-index/types.js';
+export type { WorkspaceLedger } from './workspace-ledger/types.js';

package/dist/index.js

@@ -3,6 +3,7 @@ import fs, { existsSync } from 'fs';
 import { execFile } from 'child_process';
 import dugite from 'dugite';
 import { randomBytes, createHash } from 'crypto';
+import { ledgerResolveName, mintId, ledgerRename, ledgerCurName, IdentityLedgerSchema } from '@almadar/core';
 import { EmbeddingClient } from '@almadar/llm';
 import os from 'os';
 
@@ -22,6 +23,10 @@ var LocalBackend = class {
     fs.mkdirSync(path2.dirname(absPath), { recursive: true });
     fs.writeFileSync(absPath, content, "utf-8");
   }
+  async appendFile(absPath, content) {
+    await fs.promises.mkdir(path2.dirname(absPath), { recursive: true });
+    await fs.promises.appendFile(absPath, content, "utf-8");
+  }
   async readFileBytes(absPath) {
     return fs.promises.readFile(absPath);
   }
@@ -102,6 +107,9 @@ var MemoryBackend = class {
   writeFileSync(absPath, content) {
     this.files.set(absPath, content);
   }
+  async appendFile(absPath, content) {
+    this.files.set(absPath, (this.files.get(absPath) ?? "") + content);
+  }
   async readFileBytes(absPath) {
     const b = this.bytes.get(absPath);
     if (b === void 0) throw new Error(`ENOENT: ${absPath}`);
@@ -293,7 +301,10 @@ function appMarkerFile(workDir) {
 function workspaceIndexManifestFile(workDir) {
   return path2.join(workDir, WORKSPACE_LAYOUT.ALMADAR_DIR, "index.json");
 }
-function sandboxedPath(workDir, relPath) {
+function workspaceLedgerFile(workDir) {
+  return path2.join(workDir, WORKSPACE_LAYOUT.ALMADAR_DIR, "ledger.json");
+}
+function sandboxedPath(workDir, relPath, mounts) {
   if (typeof relPath !== "string" || relPath.length === 0) {
     throw new Error("sandbox: empty relative path");
   }
@@ -303,6 +314,20 @@ function sandboxedPath(workDir, relPath) {
   if (/^[a-zA-Z]:[\\/]/.test(relPath)) {
     throw new Error(`sandbox: drive-letter paths are not allowed (${relPath})`);
   }
+  if (mounts) {
+    for (const [prefix, mountRoot] of mounts) {
+      const prefixSep = prefix + "/";
+      if (relPath === prefix || relPath.startsWith(prefixSep)) {
+        const mountAbs = path2.resolve(mountRoot);
+        const rest = relPath === prefix ? "." : relPath.slice(prefixSep.length);
+        const target2 = path2.resolve(mountAbs, rest);
+        if (target2 !== mountAbs && !target2.startsWith(mountAbs + path2.sep)) {
+          throw new Error(`sandbox: mount path escapes mount root (${relPath})`);
+        }
+        return target2;
+      }
+    }
+  }
   const rootAbs = path2.resolve(workDir);
   const target = path2.resolve(rootAbs, relPath);
   if (target !== rootAbs && !target.startsWith(rootAbs + path2.sep)) {
@@ -662,14 +687,11 @@ async function writeJsonFile(backend, absPath, value) {
   await backend.writeFile(absPath, JSON.stringify(value, null, 2));
 }
 async function appendJsonLine(backend, absPath, value) {
-  const existing = backend.exists(absPath) ? await backend.readFile(absPath) : "";
-  const ending = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
-  await backend.writeFile(absPath, existing + ending + JSON.stringify(value) + "\n");
+  await backend.appendFile(absPath, JSON.stringify(value) + "\n");
 }
 
 // src/workspace-index/types.ts
 var WORKSPACE_INDEX_SCHEMA_VERSION = 2;
-var DEFAULT_COERCION_THRESHOLD = 0.85;
 var RRF_K = 60;
 var DEFAULT_RETRIEVAL_TOP_K = 3;
 
@@ -1325,62 +1347,6 @@ var WorkspaceIndexImpl = class {
     }
     await this.rebuildManifest();
   }
-  async resolveOrbitalName(name, opts) {
-    const threshold = opts?.threshold ?? DEFAULT_COERCION_THRESHOLD;
-    if (this.entries.size === 0) {
-      return { coercedTo: null, similarity: 0, method: "identity-vector" };
-    }
-    let vector;
-    try {
-      [vector] = await this.embedOne(name);
-    } catch (err) {
-      const reason = err instanceof Error ? err.message : String(err);
-      console.warn(`[workspace-index] resolveOrbitalName: embedder failed, returning null (${reason})`);
-      return { coercedTo: null, similarity: 0, method: "identity-vector" };
-    }
-    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);
-    let vector;
-    try {
-      [vector] = await this.embedOne(fingerprint);
-    } catch (err) {
-      const reason = err instanceof Error ? err.message : String(err);
-      console.warn(`[workspace-index] resolveTraitRef: embedder failed, returning null (${reason})`);
-      return { coercedTo: null, similarity: 0, method: "identity-vector" };
-    }
-    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()) {
@@ -1750,6 +1716,172 @@ function serializeMapOfArrays(map, projectOne) {
   }
   return out;
 }
+function ledgerPath(workDir) {
+  return workspaceLedgerFile(workDir);
+}
+async function readLedger(backend, workDir) {
+  const p = ledgerPath(workDir);
+  if (!backend.exists(p)) return null;
+  try {
+    const raw = await backend.readFile(p);
+    const result = IdentityLedgerSchema.safeParse(JSON.parse(raw));
+    return result.success ? result.data : null;
+  } catch {
+    return null;
+  }
+}
+async function writeLedger(backend, workDir, ledger) {
+  await backend.writeFile(ledgerPath(workDir), JSON.stringify(serializeLedger(ledger), null, 2));
+}
+function serializeLedger(ledger) {
+  const entries = {};
+  for (const [id, entry] of Object.entries(ledger.entries)) {
+    entries[id] = serializeEntry(entry);
+  }
+  return { schemaVersion: ledger.schemaVersion, entries };
+}
+function serializeEntry(entry) {
+  const row = {
+    id: entry.id,
+    kind: entry.kind,
+    bakedName: entry.bakedName,
+    curName: entry.curName,
+    renames: entry.renames.map((r) => ({ from: r.from, to: r.to, at: r.at })),
+    owner: entry.owner
+  };
+  if (entry.parent !== void 0) row.parent = entry.parent;
+  return row;
+}
+
+// src/workspace-ledger/ledger-impl.ts
+var WorkspaceLedgerImpl = class {
+  constructor(deps) {
+    this.deps = deps;
+    this.ledger = emptyLedger();
+    /** Serialized persists so concurrent writes don't race the file. */
+    this.persistQueue = Promise.resolve();
+    this.deps.sinks.subscribe({
+      onWrite: (event) => this.onWorkspaceWrite(event)
+    });
+  }
+  async onWorkspaceWrite(event) {
+    if (event.kind !== "orbital") return;
+    const slice = extractLedgerSlice(event.content);
+    if (slice !== null) {
+      this.ingestOrbSlice(slice);
+    } else if (isJsonObject(event.content) && this.resolve("orbital", event.name) === null) {
+      this.mint("orbital", event.name);
+    }
+    await this.persistQueue;
+  }
+  resolve(kind, name) {
+    return ledgerResolveName(this.ledger, kind, name);
+  }
+  mint(kind, name) {
+    if (kind === "palette") {
+      throw new Error("WorkspaceLedger.mint: palette ids are manifest-owned, not name-ledger rows");
+    }
+    if (this.resolve(kind, name) !== null) {
+      throw new Error(`WorkspaceLedger.mint: duplicate curName "${name}" within kind "${kind}"`);
+    }
+    const id = mintId(kind);
+    const entry = {
+      id,
+      kind,
+      bakedName: name,
+      curName: name,
+      renames: [],
+      owner: "workspace"
+    };
+    this.ledger = { ...this.ledger, entries: { ...this.ledger.entries, [id]: entry } };
+    void this.persist();
+    return id;
+  }
+  rename(id, to, at) {
+    if (this.ledger.entries[id] === void 0) {
+      throw new Error(`WorkspaceLedger.rename: unknown id "${id}"`);
+    }
+    this.ledger = ledgerRename(this.ledger, id, to, String(at));
+    void this.persist();
+  }
+  curName(id) {
+    return ledgerCurName(this.ledger, id);
+  }
+  entry(id) {
+    return this.ledger.entries[id] ?? null;
+  }
+  snapshot() {
+    return cloneLedger(this.ledger);
+  }
+  ingestOrbSlice(slice) {
+    const entries = { ...this.ledger.entries };
+    let changed = false;
+    for (const [id, entry] of Object.entries(slice.entries)) {
+      if (entries[id] === void 0) {
+        entries[id] = entry;
+        changed = true;
+      }
+    }
+    if (!changed) return;
+    this.ledger = { ...this.ledger, entries };
+    void this.persist();
+  }
+  async warm() {
+    const loaded = await readLedger(this.deps.backend, this.deps.workDir);
+    this.ledger = loaded ?? emptyLedger();
+    const names = this.deps.listOrbitals();
+    for (const name of names) {
+      const content = this.deps.readOrbital(name);
+      if (content === null) continue;
+      const slice = extractLedgerSlice(content);
+      if (slice !== null) this.ingestOrbSlice(slice);
+    }
+    for (const name of names) {
+      if (this.resolve("orbital", name) === null) this.mint("orbital", name);
+    }
+    await this.persistQueue;
+  }
+  persist() {
+    const snapshot = this.ledger;
+    const next = this.persistQueue.then(async () => {
+      await writeLedger(this.deps.backend, this.deps.workDir, snapshot);
+      await this.deps.sinks.notifyAll({
+        kind: "workspace-ledger",
+        content: serializeLedger(snapshot)
+      });
+    });
+    this.persistQueue = next.catch(() => void 0);
+    return next;
+  }
+};
+function emptyLedger() {
+  return { schemaVersion: 1, entries: {} };
+}
+function cloneLedger(ledger) {
+  const entries = {};
+  for (const [id, entry] of Object.entries(ledger.entries)) {
+    entries[id] = { ...entry, renames: entry.renames.map((r) => ({ ...r })) };
+  }
+  return { schemaVersion: ledger.schemaVersion, entries };
+}
+function isJsonObject(content) {
+  try {
+    const root = JSON.parse(content);
+    return root !== null && typeof root === "object" && !Array.isArray(root);
+  } catch {
+    return false;
+  }
+}
+function extractLedgerSlice(content) {
+  try {
+    const root = JSON.parse(content);
+    if (root === null || typeof root !== "object" || Array.isArray(root)) return null;
+    const result = IdentityLedgerSchema.safeParse(root.ledger);
+    return result.success ? result.data : null;
+  } catch {
+    return null;
+  }
+}
 
 // src/service.ts
 var COORD_FILES = {
@@ -1770,6 +1902,8 @@ var WorkspaceServiceImpl = class {
   constructor(args) {
     /** Per-absolute-path serial queue. */
     this.writeQueue = /* @__PURE__ */ new Map();
+    /** Mount prefix → resolved absolute directory. Built from constructor `mounts` + runtime `mountReadonly`. */
+    this.mountMap = /* @__PURE__ */ new Map();
     this.workDir = args.workDir;
     this.backend = args.backend;
     this.sinks = args.sinks;
@@ -1787,6 +1921,16 @@ var WorkspaceServiceImpl = class {
       readSchema: () => this.readSchema(),
       readHistory: (orbital) => this.readHistory(orbital)
     });
+    this.ledger = new WorkspaceLedgerImpl({
+      workDir: this.workDir,
+      backend: this.backend,
+      sinks: this.sinks,
+      listOrbitals: () => this.listOrbitals(),
+      readOrbital: (name) => this.readOrbital(name)
+    });
+    if (args.mounts) {
+      for (const m of args.mounts) this.mountMap.set(m.prefix, path2.resolve(m.absPath));
+    }
   }
   // === Identity ===
   get appId() {
@@ -2109,7 +2253,7 @@ var WorkspaceServiceImpl = class {
   }
   // === Sandboxed generic file I/O ===
   async readFile(relPath) {
-    const abs = sandboxedPath(this.workDir, relPath);
+    const abs = this.sandbox(relPath);
     if (!this.backend.exists(abs)) return null;
     try {
       return await this.backend.readFile(abs);
@@ -2118,7 +2262,8 @@ var WorkspaceServiceImpl = class {
     }
   }
   async writeFile(relPath, content) {
-    const abs = sandboxedPath(this.workDir, relPath);
+    this.assertNotMounted(relPath);
+    const abs = this.sandbox(relPath);
     await this.withLock(abs, async () => {
       await this.ensureParent(abs);
       await this.backend.writeFile(abs, content);
@@ -2126,7 +2271,8 @@ var WorkspaceServiceImpl = class {
     await this.emit({ kind: "file", relPath, content });
   }
   async removeFile(relPath) {
-    const abs = sandboxedPath(this.workDir, relPath);
+    this.assertNotMounted(relPath);
+    const abs = this.sandbox(relPath);
     let removed = false;
     await this.withLock(abs, async () => {
       if (!this.backend.exists(abs)) return;
@@ -2136,7 +2282,7 @@ var WorkspaceServiceImpl = class {
     if (removed) await this.emit({ kind: "file-removed", relPath });
   }
   async listTree(relPath) {
-    const base = relPath === void 0 ? this.workDir : sandboxedPath(this.workDir, relPath);
+    const base = relPath === void 0 ? this.workDir : this.sandbox(relPath);
     if (!this.backend.exists(base)) return [];
     const out = [];
     await walk(this.backend, base, this.workDir, out);
@@ -2145,12 +2291,39 @@ var WorkspaceServiceImpl = class {
   async exists(relPath) {
     let abs;
     try {
-      abs = sandboxedPath(this.workDir, relPath);
+      abs = this.sandbox(relPath);
     } catch {
       return false;
     }
     return this.backend.exists(abs);
   }
+  // === Read-only mounts ===
+  mountReadonly(prefix, absPath) {
+    if (this.mountMap.has(prefix)) {
+      throw new Error(`mount: prefix "${prefix}" already registered`);
+    }
+    this.mountMap.set(prefix, path2.resolve(absPath));
+  }
+  isMounted(relPath) {
+    try {
+      for (const [prefix] of this.mountMap) {
+        if (relPath === prefix || relPath.startsWith(prefix + "/")) return true;
+      }
+      return false;
+    } catch {
+      return false;
+    }
+  }
+  /** Resolve a sandboxed path through mounts. */
+  sandbox(relPath) {
+    return sandboxedPath(this.workDir, relPath, this.mountMap.size > 0 ? this.mountMap : void 0);
+  }
+  /** Throw if relPath resolves to a mount (write/remove are blocked). */
+  assertNotMounted(relPath) {
+    if (this.isMounted(relPath)) {
+      throw new Error(`sandbox: cannot write to read-only mount (${relPath})`);
+    }
+  }
   // === Git ===
   async commitAndPush(opts) {
     if (!this.git) return null;
@@ -2361,6 +2534,25 @@ async function openWorkspace(opts) {
   }
   return openWorkspaceInternal(opts);
 }
+var WORKSPACE_OWNED_ENTRIES = /* @__PURE__ */ new Set([".almadar", "orbitals", "schema.orb", ".git", ".gitignore"]);
+async function guardForeignMintTarget(backend, workDir) {
+  if (readAppMarker(backend, workDir) !== null) return;
+  if (backend.exists(path2.join(workDir, "schema.orb"))) return;
+  if (backend.exists(path2.join(workDir, ".almadar", "sessions"))) return;
+  if (!backend.exists(workDir)) return;
+  if (process.env["ALMADAR_WORKSPACE_ADOPT_NONEMPTY"] === "1") return;
+  let entries;
+  try {
+    entries = await backend.readdir(workDir);
+  } catch {
+    return;
+  }
+  const foreign = entries.filter((e) => !WORKSPACE_OWNED_ENTRIES.has(e));
+  if (foreign.length === 0) return;
+  throw new Error(
+    `refusing to mint a workspace into ${workDir} \u2014 it already contains non-workspace content (${foreign.slice(0, 5).join(", ")}${foreign.length > 5 ? ", \u2026" : ""}). Pass an empty/dedicated workDir, or set ALMADAR_WORKSPACE_ADOPT_NONEMPTY=1 to adopt this directory anyway.`
+  );
+}
 async function openWorkspaceInternal(opts) {
   const backend = opts.backend === "memory" ? new MemoryBackend() : new LocalBackend();
   const sinks = new SinkManager();
@@ -2368,6 +2560,7 @@ async function openWorkspaceInternal(opts) {
   if (resolved === null) return null;
   const bare = opts.bare === true && opts.adopt !== void 0;
   if (!bare) {
+    await guardForeignMintTarget(backend, resolved.workDir);
     await ensureSkeleton(backend, resolved.workDir);
     await writeMintTemplatesIfMissing(
       backend,
@@ -2405,10 +2598,12 @@ async function openWorkspaceInternal(opts) {
     appId: resolved.appId,
     git,
     github: opts.github,
-    archiveBackend: opts.archiveBackend
+    archiveBackend: opts.archiveBackend,
+    mounts: opts.mounts
   });
   if (!bare) {
     await service.index.warm();
+    await service.ledger.warm();
   }
   return service;
 }
@@ -2598,6 +2793,6 @@ async function openAccount(opts = {}) {
   };
 }
 
-export { DEFAULT_COERCION_THRESHOLD, DEFAULT_RETRIEVAL_TOP_K, RRF_K, WORKSPACE_INDEX_SCHEMA_VERSION, deleteWorkspace, listWorkspaces, openAccount, openWorkspace };
+export { DEFAULT_RETRIEVAL_TOP_K, RRF_K, WORKSPACE_INDEX_SCHEMA_VERSION, deleteWorkspace, listWorkspaces, openAccount, openWorkspace };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map