@almadar/workspace 0.11.4 → 0.11.6

package/dist/internal/backends/local.d.ts

@@ -4,6 +4,7 @@ export declare class LocalBackend implements WorkspaceBackend {
     readFileSync(absPath: string): string;
     writeFile(absPath: string, content: string): Promise<void>;
     writeFileSync(absPath: string, content: string): void;
+    appendFile(absPath: string, content: string): Promise<void>;
     readFileBytes(absPath: string): Promise<Uint8Array>;
     writeFileBytes(absPath: string, bytes: Uint8Array): Promise<void>;
     exists(absPath: string): boolean;

package/dist/internal/backends/memory.d.ts

@@ -10,6 +10,7 @@ export declare class MemoryBackend implements WorkspaceBackend {
     readFileSync(absPath: string): string;
     writeFile(absPath: string, content: string): Promise<void>;
     writeFileSync(absPath: string, content: string): void;
+    appendFile(absPath: string, content: string): Promise<void>;
     readFileBytes(absPath: string): Promise<Uint8Array>;
     writeFileBytes(absPath: string, bytes: Uint8Array): Promise<void>;
     exists(absPath: string): boolean;

package/dist/internal/memory-files.d.ts

@@ -22,5 +22,11 @@ export declare function readJsonLines<T extends JsonObject>(backend: WorkspaceBa
  * Append a single JSON value as a line. Used for trace + history streams.
  * Caller is responsible for any per-path serialization (the service's
  * write queue handles that).
+ *
+ * Must be a REAL append (O_APPEND), never read-concat-rewrite: a rewrite
+ * truncates first, so a process killed mid-write zeroes the entire stream
+ * (C-TRACE-APPEND-TRUNCATE — the 0-byte trace.jsonl class). This function is
+ * the sole writer of these streams, so every line it writes ends in `\n` and
+ * the file never needs a separator probe.
  */
 export declare function appendJsonLine<T extends JsonObject>(backend: WorkspaceBackend, absPath: string, value: T): Promise<void>;

package/dist/internal/path-layout.d.ts

@@ -46,11 +46,17 @@ export declare function compiledFile(workDir: string, relPath: string): string;
 export declare function appMarkerFile(workDir: string): string;
 /** Workspace-level index manifest path. */
 export declare function workspaceIndexManifestFile(workDir: string): string;
+/** Workspace-level identity-ledger path. */
+export declare function workspaceLedgerFile(workDir: string): string;
 /**
  * Resolve a user-supplied relative path within the sandbox. Rejects
  * absolute paths, `..` traversal, and any path that resolves outside
  * `workDir`. Returns the absolute resolved path on success.
+ *
+ * When `mounts` is supplied, path prefixes like `@std/…` resolve against
+ * the mount's absolute root instead of `workDir`. Mounts bypass the
+ * `workDir` traversal guard but enforce their own.
  */
-export declare function sandboxedPath(workDir: string, relPath: string): string;
+export declare function sandboxedPath(workDir: string, relPath: string, mounts?: ReadonlyMap<string, string>): string;
 /** Validate an orbital logical name — no path separators, no `..`. */
 export declare function assertOrbitalName(name: string): void;

package/dist/internal/types.d.ts

@@ -13,6 +13,12 @@ export interface WorkspaceBackend {
     readFileSync(absPath: string): string;
     writeFile(absPath: string, content: string): Promise<void>;
     writeFileSync(absPath: string, content: string): void;
+    /**
+     * Append to a file (create if absent) without truncating — O_APPEND on real
+     * filesystems. Required for line streams (trace/history): a truncate-rewrite
+     * "append" zeroes the whole stream when the process is killed mid-write.
+     */
+    appendFile(absPath: string, content: string): Promise<void>;
     /** Binary read/write — for git bundle artifacts (durable archive bytes). */
     readFileBytes(absPath: string): Promise<Uint8Array>;
     writeFileBytes(absPath: string, bytes: Uint8Array): Promise<void>;

package/dist/service.d.ts

@@ -7,11 +7,12 @@
  * @packageDocumentation
  */
 import type { JsonObject, JsonValue } from '@almadar/core';
-import type { FileTreeNode, GitHubConfig, GitStatusInfo, InstantiateWorkspaceSeed, SnapshotMeta, WorkspaceArchiveBackend, WorkspaceObserver, WorkspaceService, WorkspaceWatchEvent } from './types.js';
+import type { FileTreeNode, GitHubConfig, GitStatusInfo, InstantiateWorkspaceSeed, MountEntry, SnapshotMeta, WorkspaceArchiveBackend, WorkspaceObserver, WorkspaceService, WorkspaceWatchEvent } from './types.js';
 import type { WorkspaceBackend } from './internal/types.js';
 import { SinkManager } from './internal/sink-manager.js';
 import { GitClient } from './internal/git-client.js';
 import type { EmbedderPort, WorkspaceIndex } from './workspace-index/types.js';
+import type { WorkspaceLedger } from './workspace-ledger/types.js';
 interface ServiceCtorArgs {
     workDir: string;
     backend: WorkspaceBackend;
@@ -21,6 +22,7 @@ interface ServiceCtorArgs {
     git?: GitClient;
     github?: GitHubConfig;
     archiveBackend?: WorkspaceArchiveBackend;
+    mounts?: MountEntry[];
 }
 export declare class WorkspaceServiceImpl implements WorkspaceService {
     readonly workDir: string;
@@ -32,7 +34,10 @@ export declare class WorkspaceServiceImpl implements WorkspaceService {
     private readonly archiveBackend;
     /** Per-absolute-path serial queue. */
     private readonly writeQueue;
+    /** Mount prefix → resolved absolute directory. Built from constructor `mounts` + runtime `mountReadonly`. */
+    private readonly mountMap;
     readonly index: WorkspaceIndex;
+    readonly ledger: WorkspaceLedger;
     constructor(args: ServiceCtorArgs);
     get appId(): string | undefined;
     setAppId(id: string): void;
@@ -86,6 +91,12 @@ export declare class WorkspaceServiceImpl implements WorkspaceService {
     removeFile(relPath: string): Promise<void>;
     listTree(relPath?: string): Promise<FileTreeNode[]>;
     exists(relPath: string): Promise<boolean>;
+    mountReadonly(prefix: string, absPath: string): void;
+    isMounted(relPath: string): boolean;
+    /** Resolve a sandboxed path through mounts. */
+    private sandbox;
+    /** Throw if relPath resolves to a mount (write/remove are blocked). */
+    private assertNotMounted;
     commitAndPush(opts: {
         message: string;
         tags?: string[];

package/dist/types.d.ts

@@ -9,6 +9,7 @@
 import type { JsonObject, JsonValue, OrbitalSchema } from '@almadar/core';
 import type { ProviderConfig } from '@almadar/llm';
 import type { EmbedderPort, WorkspaceIndex } from './workspace-index/types.js';
+import type { WorkspaceLedger } from './workspace-ledger/types.js';
 /**
  * The only extension point. Consumers register one observer via
  * `service.subscribe(observer)`; every workspace write fans out
@@ -100,6 +101,9 @@ export type WorkspaceWriteEvent = {
 } | {
     kind: 'workspace-index-manifest';
     content: JsonObject;
+} | {
+    kind: 'workspace-ledger';
+    content: JsonObject;
 };
 /**
  * Emitted by {@link WorkspaceService.watch} when storage changes underneath the
@@ -173,6 +177,13 @@ export interface FileTreeNode {
     /** Byte size for files; `0` for directories. */
     size: number;
 }
+/** Read-only mount entry — makes an external absolute directory available under a workspace-prefix path. */
+export interface MountEntry {
+    /** Workspace-relative prefix, e.g. `@std`. Must not contain path separators or `..`. */
+    prefix: string;
+    /** Absolute path to the backing directory on the local filesystem. */
+    absPath: string;
+}
 /**
  * Factory input. Lifecycle resolution order: `adopt` → resume-from-disk →
  * `restore` backend → `github` clone → mint fresh.
@@ -213,6 +224,13 @@ export interface OpenWorkspaceOptions {
     create?: boolean;
     /** Storage selector. `'memory'` is for tests; `'local'` is default. */
     backend?: 'local' | 'memory';
+    /**
+     * Read-only mounts — expose external absolute directories under
+     * workspace-relative path prefixes (e.g. `@std` → `/path/to/std`).
+     * ReadFile / listTree / exists resolve through mounts transparently;
+     * writeFile / removeFile reject mounted paths.
+     */
+    mounts?: MountEntry[];
     /** Optional project name baked into the mint-time schema template. */
     projectName?: string;
     /**
@@ -329,6 +347,14 @@ export interface WorkspaceService {
     removeFile(relPath: string): Promise<void>;
     listTree(relPath?: string): Promise<FileTreeNode[]>;
     exists(relPath: string): Promise<boolean>;
+    /**
+     * Add a read-only mount at runtime — makes an external absolute directory
+     * available under a workspace-path prefix. ReadFile / listTree / exists
+     * resolve through the mount transparently; writeFile / removeFile reject it.
+     */
+    mountReadonly(prefix: string, absPath: string): void;
+    /** True when `relPath` resolves to a read-only mount. */
+    isMounted(relPath: string): boolean;
     commitAndPush(opts: {
         message: string;
         tags?: string[];
@@ -361,6 +387,7 @@ export interface WorkspaceService {
      */
     watch(relPath: string, onChange: (event: WorkspaceWatchEvent) => void): () => void;
     readonly index: WorkspaceIndex;
+    readonly ledger: WorkspaceLedger;
     dispose(): Promise<void>;
 }
 /**

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

@@ -45,8 +45,7 @@ export declare function composeExtraTraitIdentityFingerprint(emit: {
 /**
  * Derive the alias an entry would canonically be referenced by. Used by
  * the sidecar baker to store the `alias` field next to each extraTrait
- * identity vector — also the value `resolveTraitRef` returns as
- * `coercedTo` when a match fires.
+ * identity vector.
  */
 export declare function deriveExtraTraitAlias(emit: {
     ref: string;

package/dist/workspace-index/index-impl.d.ts

@@ -9,7 +9,7 @@
 import type { JsonObject } from '@almadar/core';
 import type { WorkspaceBackend } from '../internal/types.js';
 import type { SinkManager } from '../internal/sink-manager.js';
-import type { EmbedderPort, EntityBinding, EventEdge, RecentlyEditedOptions, ResolveOptions, ResolveResult, RetrievalOptions, RetrievalResult, RuleBinding, TraitRefEmit, WorkspaceIndex, WorkspaceIndexStats } from './types.js';
+import type { EmbedderPort, EntityBinding, EventEdge, RecentlyEditedOptions, RetrievalOptions, RetrievalResult, RuleBinding, WorkspaceIndex, WorkspaceIndexStats } from './types.js';
 export interface WorkspaceIndexDeps {
     workDir: string;
     backend: WorkspaceBackend;
@@ -42,10 +42,6 @@ export declare class WorkspaceIndexImpl implements WorkspaceIndex {
     constructor(deps: WorkspaceIndexDeps);
     private onWorkspaceWrite;
     warm(): Promise<void>;
-    resolveOrbitalName(name: string, opts?: ResolveOptions): Promise<ResolveResult>;
-    resolveTraitRef(emit: TraitRefEmit, orbitalContext: {
-        orbitalName: string;
-    }, opts?: ResolveOptions): Promise<ResolveResult>;
     stats(): WorkspaceIndexStats;
     retrieveOrbitalsForPrompt(prompt: string, opts?: RetrievalOptions): Promise<readonly RetrievalResult[]>;
     findByToken(query: string): readonly string[];

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

@@ -4,8 +4,8 @@
  *
  * @packageDocumentation
  */
-export type { EmbedderPort, ExtraTraitIdentity, OrbitalIndexEntry, ResolveOptions, ResolveResult, TraitRefEmit, WorkspaceIndex, WorkspaceIndexStats, } from './types.js';
-export { DEFAULT_COERCION_THRESHOLD, WORKSPACE_INDEX_SCHEMA_VERSION, } from './types.js';
+export type { EmbedderPort, ExtraTraitIdentity, OrbitalIndexEntry, WorkspaceIndex, WorkspaceIndexStats, } from './types.js';
+export { WORKSPACE_INDEX_SCHEMA_VERSION, } from './types.js';
 export { WorkspaceIndexImpl } from './index-impl.js';
 export type { WorkspaceIndexDeps } from './index-impl.js';
 export { createDefaultEmbedder } from './embedder.js';

package/dist/workspace-index/types.d.ts

@@ -14,8 +14,6 @@ import type { JsonObject } from '@almadar/core';
  *  Existing v1 sidecars get re-baked transparently on next openWorkspace.
  */
 export declare const WORKSPACE_INDEX_SCHEMA_VERSION: 2;
-/** Default coercion threshold per the doc's locked decision. */
-export declare const DEFAULT_COERCION_THRESHOLD: 0.85;
 /** RRF fusion constant (Elastic / OpenSearch convention). */
 export declare const RRF_K: 60;
 /** Default top-K for retrieveOrbitalsForPrompt. */
@@ -68,33 +66,6 @@ export interface OrbitalIndexEntry {
     /** Epoch ms at bake time — debugging only. */
     bakedAt: number;
 }
-/**
- * Input to `resolveTraitRef` — the LLM's emitted extraTraits entry,
- * narrowed to the fields the coercion needs to see. Mirrors the
- * `RawExtraTraitRef` shape rabit's analyzer constructs.
- */
-export interface TraitRefEmit {
-    ref: string;
-    name?: string;
-    linkedEntity?: string;
-}
-/**
- * Common result shape for both `resolveOrbitalName` and
- * `resolveTraitRef`. `coercedTo` is null when no existing entity
- * exceeded the threshold — the emit is genuinely new.
- */
-export interface ResolveResult {
-    coercedTo: string | null;
-    similarity: number;
-    method: 'identity-vector';
-}
-/**
- * Options for both `resolveOrbitalName` and `resolveTraitRef`. The
- * default threshold (0.85) lives in `DEFAULT_COERCION_THRESHOLD`.
- */
-export interface ResolveOptions {
-    threshold?: number;
-}
 /**
  * Stats surface for diagnostics. Cheap to compute (read in-memory
  * state).
@@ -116,26 +87,6 @@ export interface WorkspaceIndex {
      * already-warm sidecar is a no-op (checksum matches).
      */
     warm(): Promise<void>;
-    /**
-     * R-10 coercion. Embed `name`, cosine-match against every orbital's
-     * identity vector, return the best match if it exceeds the
-     * threshold. Returns `{ coercedTo: null, ... }` when below threshold
-     * or when no orbitals exist in the workspace.
-     */
-    resolveOrbitalName(name: string, opts?: ResolveOptions): Promise<ResolveResult>;
-    /**
-     * R-8 coercion. Embed an LLM-emitted trait emit, cosine-match against
-     * the existing `extraTraits[]` identity vectors on the named orbital.
-     * Returns the existing entry's `ref` (or its `name` rename) as
-     * `coercedTo` when match exceeds threshold; null when the emit is a
-     * genuinely new addition.
-     *
-     * Scoped per orbital — the same trait import on two different orbitals
-     * is structurally legitimate, so we don't cross-coerce.
-     */
-    resolveTraitRef(emit: TraitRefEmit, orbitalContext: {
-        orbitalName: string;
-    }, opts?: ResolveOptions): Promise<ResolveResult>;
     /**
      * Phase B — RRF-hybrid prompt retrieval. Embed the prompt, run sparse
      * BM25 against the workspace token table, fuse via Reciprocal Rank

package/dist/workspace-ledger/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Public surface of the workspace identity-ledger module. Re-exported from
+ * the top-level `@almadar/workspace` barrel.
+ *
+ * @packageDocumentation
+ */
+export type { WorkspaceLedger } from './types.js';
+export { WorkspaceLedgerImpl } from './ledger-impl.js';
+export type { WorkspaceLedgerDeps } from './ledger-impl.js';

package/dist/workspace-ledger/ledger-impl.d.ts

@@ -0,0 +1,42 @@
+/**
+ * `WorkspaceLedgerImpl` — the runtime holding one `IdentityLedger` per
+ * workspace. A sibling of `WorkspaceIndexImpl`: it subscribes to the
+ * `SinkManager` to auto-ingest `.orb` ledger slices on `orbital` writes, and
+ * persists to `.almadar/ledger.json`, emitting a `workspace-ledger` mirror
+ * event after each persist.
+ *
+ * The workspace ledger is runtime-owned and authoritative: `ingestOrbSlice`
+ * only ever introduces NEW ids; an id already present keeps its row. Renames
+ * flow through explicit `rename()` calls (from rabit), never inferred from
+ * file events.
+ *
+ * @packageDocumentation
+ */
+import type { IdKind, IdentityLedger, LedgerEntry, LedgerKind } from '@almadar/core';
+import type { WorkspaceBackend } from '../internal/types.js';
+import type { SinkManager } from '../internal/sink-manager.js';
+import type { WorkspaceLedger } from './types.js';
+export interface WorkspaceLedgerDeps {
+    workDir: string;
+    backend: WorkspaceBackend;
+    sinks: SinkManager;
+    listOrbitals: () => string[];
+    readOrbital: (name: string) => string | null;
+}
+export declare class WorkspaceLedgerImpl implements WorkspaceLedger {
+    private readonly deps;
+    private ledger;
+    /** Serialized persists so concurrent writes don't race the file. */
+    private persistQueue;
+    constructor(deps: WorkspaceLedgerDeps);
+    private onWorkspaceWrite;
+    resolve(kind: LedgerKind, name: string): string | null;
+    mint(kind: IdKind, name: string): string;
+    rename(id: string, to: string, at: number): void;
+    curName(id: string): string | null;
+    entry(id: string): LedgerEntry | null;
+    snapshot(): IdentityLedger;
+    ingestOrbSlice(slice: IdentityLedger): void;
+    warm(): Promise<void>;
+    private persist;
+}

package/dist/workspace-ledger/persistence.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Identity-ledger persistence — the single JSON file `.almadar/ledger.json`.
+ *
+ * Mirrors `workspace-index/manifest.ts`: same file helpers, same path-layout
+ * discipline. Reads validate against the core `IdentityLedgerSchema`; an
+ * unparseable / wrong-version file reads as `null` (the caller substitutes an
+ * empty ledger), matching the sidecar null-on-mismatch posture.
+ *
+ * @packageDocumentation
+ */
+import type { JsonObject } from '@almadar/core';
+import type { IdentityLedger } from '@almadar/core';
+import type { WorkspaceBackend } from '../internal/types.js';
+export declare function ledgerPath(workDir: string): string;
+export declare function readLedger(backend: WorkspaceBackend, workDir: string): Promise<IdentityLedger | null>;
+export declare function writeLedger(backend: WorkspaceBackend, workDir: string, ledger: IdentityLedger): Promise<void>;
+/** Project the ledger into a plain `JsonObject` for persistence + the mirror event. */
+export declare function serializeLedger(ledger: IdentityLedger): JsonObject;

package/dist/workspace-ledger/types.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Public surface of the workspace identity ledger (Rabit V4, Phase 6).
+ *
+ * One `IdentityLedger` (the core type, schemaVersion 1) per workspace — the
+ * runtime-owned, authoritative name↔id map. Resolution is exact within a kind;
+ * there is no similarity, no threshold, no fallback. Baked/emitted `.orb`
+ * slices only ever introduce NEW ids (row-level merge); an id already present
+ * keeps its workspace row.
+ *
+ * @packageDocumentation
+ */
+import type { IdKind, IdentityLedger, LedgerEntry, LedgerKind } from '@almadar/core';
+export interface WorkspaceLedger {
+    /** Exact `curName` match within `kind`, else null. No similarity. */
+    resolve(kind: LedgerKind, name: string): string | null;
+    /**
+     * Mint a fresh id, insert a workspace-owned row, persist. Throws when
+     * `resolve(kind, name)` already returns an id (duplicate curName within a
+     * kind is a caller bug) or when `kind` is `'palette'` (manifest-owned).
+     */
+    mint(kind: IdKind, name: string): string;
+    /** Rename an id's `curName` + append rename history, persist. Throws if id unknown. */
+    rename(id: string, to: string, at: number): void;
+    /** Current display name for an id, or null when unknown. */
+    curName(id: string): string | null;
+    /** The row for an id, or null when unknown. */
+    entry(id: string): LedgerEntry | null;
+    /** A deep clone of the ledger — no aliasing of internal state. */
+    snapshot(): IdentityLedger;
+    /**
+     * Row-level merge of a baked/emitted `.orb` ledger slice: add rows whose id
+     * is NOT already present; present ids keep the workspace row untouched.
+     * Persists once when the merge changed anything.
+     */
+    ingestOrbSlice(slice: IdentityLedger): void;
+    /** Load `.almadar/ledger.json`, then ingest every existing `orbitals/*.orb` slice. */
+    warm(): Promise<void>;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almadar/workspace",
-  "version": "0.11.4",
+  "version": "0.11.6",
   "description": "Storage-agnostic workspace primitives shared by Almadar consumers. One service, six exports, hidden paths, single observer. See docs/Almadar_Workspace.md.",
   "type": "module",
   "main": "./dist/index.js",
@@ -25,13 +25,13 @@
   },
   "license": "BUSL-1.1",
   "dependencies": {
-    "@almadar/core": ">=9.6.1",
-    "@almadar/llm": "^2.16.0",
+    "@almadar/core": "^10.31.0",
+    "@almadar/llm": "^2.35.0",
     "dugite": "^3.2.2",
     "typescript": "^5.4.0"
   },
   "devDependencies": {
-    "@almadar/eslint-plugin": ">=2.7.0",
+    "@almadar/eslint-plugin": "^2.14.0",
     "@types/node": "^22.0.0",
     "@typescript-eslint/parser": "8.56.0",
     "eslint": "^10.0.0",

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

@@ -1,14 +0,0 @@
-/**
- * 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 {};