@almadar/workspace 0.11.5 → 0.11.7

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

@@ -11,16 +11,16 @@
  */
 /** Single source of truth for workspace directory layout. */
 export declare const WORKSPACE_LAYOUT: {
-    readonly ALMADAR_DIR: ".almadar";
-    readonly ORBITALS_DIR: "orbitals";
-    readonly SESSIONS_DIR: ".almadar/sessions";
-    readonly COORDINATOR_DIR: ".almadar/sessions/Coordinator";
-    readonly TRACE_FILE: ".almadar/trace.jsonl";
-    readonly SCHEMA_FILE: "schema.orb";
-    readonly COMPILED_DIR: "apps";
-    readonly APP_MARKER: ".almadar/app-marker.json";
-    readonly USER_MEMORY: ".almadar/user.orb";
-    readonly PROJECT_MEMORY: ".almadar/project.orb";
+    readonly ALMADAR_DIR: '.almadar';
+    readonly ORBITALS_DIR: 'orbitals';
+    readonly SESSIONS_DIR: '.almadar/sessions';
+    readonly COORDINATOR_DIR: '.almadar/sessions/Coordinator';
+    readonly TRACE_FILE: '.almadar/trace.jsonl';
+    readonly SCHEMA_FILE: 'schema.orb';
+    readonly COMPILED_DIR: 'apps';
+    readonly APP_MARKER: '.almadar/app-marker.json';
+    readonly USER_MEMORY: '.almadar/user.orb';
+    readonly PROJECT_MEMORY: '.almadar/project.orb';
 };
 /** Logical orbital name → absolute `.orb` path. */
 export declare function orbitalFile(workDir: string, name: string): string;
@@ -46,6 +46,8 @@ 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

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

@@ -12,6 +12,7 @@ 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;
@@ -36,6 +37,7 @@ export declare class WorkspaceServiceImpl implements WorkspaceService {
     /** 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;

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
@@ -383,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.5",
+  "version": "0.11.7",
   "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,19 +25,21 @@
   },
   "license": "BUSL-1.1",
   "dependencies": {
-    "@almadar/core": "^10.26.0",
-    "@almadar/llm": "^2.31.0",
+    "@almadar/core": "^10.34.0",
+    "@almadar/llm": "^2.36.0",
     "dugite": "^3.2.2",
     "typescript": "^5.4.0"
   },
   "devDependencies": {
-    "@almadar/eslint-plugin": "^2.14.0",
+    "@almadar/eslint-plugin": "^2.15.0",
     "@types/node": "^22.0.0",
     "@typescript-eslint/parser": "8.56.0",
     "eslint": "^10.0.0",
     "tsup": "^8.0.0",
     "vitest": "^3.2.4",
-    "turbo": "^2.8.17"
+    "turbo": "^2.8.17",
+    "@typescript/native": "npm:typescript@^7.0.2",
+    "typescript": "npm:@typescript/typescript6@^6.0.2"
   },
   "scripts": {
     "build": "tsup && tsc --declaration --emitDeclarationOnly --outDir dist --rootDir src --skipLibCheck || true",

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 {};