@almadar/workspace 0.1.3 → 0.1.4

package/dist/types.d.ts

@@ -7,6 +7,7 @@
  * @packageDocumentation
  */
 import type { JsonObject, JsonValue } from '@almadar/core';
+import type { EmbedderPort, WorkspaceIndex } from './workspace-index/types.js';
 /**
  * The only extension point. Consumers register one observer via
  * `service.subscribe(observer)`; every workspace write fans out
@@ -152,6 +153,13 @@ export interface OpenWorkspaceOptions {
     backend?: 'local' | 'memory';
     /** Optional project name baked into the mint-time schema template. */
     projectName?: string;
+    /**
+     * Embedder used by the workspace index (R-10 + R-8 coercion).
+     * Defaults to `createDefaultEmbedder()` (lazy `@almadar/llm`
+     * EmbeddingClient on openrouter) when omitted; tests inject a
+     * deterministic mock.
+     */
+    embedder?: EmbedderPort;
 }
 /**
  * The single workspace I/O surface. Every consumer (rabit, apps/builder,
@@ -218,5 +226,6 @@ export interface WorkspaceService {
     pullIfLinked(): Promise<boolean>;
     gitStatus(): Promise<GitStatusInfo>;
     subscribe(observer: WorkspaceObserver): () => void;
+    readonly index: WorkspaceIndex;
     dispose(): Promise<void>;
 }

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

@@ -0,0 +1,8 @@
+/**
+ * Cosine similarity. Defensive: zero-vector and length-mismatch
+ * return 0 instead of throwing or returning NaN — a malformed manifest
+ * entry shouldn't crash the index.
+ *
+ * @packageDocumentation
+ */
+export declare function cosineSimilarity(a: readonly number[], b: readonly number[]): number;

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

@@ -0,0 +1,24 @@
+/**
+ * Embedder port + production binding to `@almadar/llm`'s
+ * `EmbeddingClient`.
+ *
+ * The port lets tests inject a deterministic mock without paying for
+ * real network calls. Production wiring constructs an `EmbeddingClient`
+ * once per workspace open and reuses it for every bake.
+ *
+ * @packageDocumentation
+ */
+import type { EmbedderPort } from './types.js';
+/**
+ * Production embedder backed by `@almadar/llm`'s `EmbeddingClient` on
+ * the openrouter provider (bge-base-en-v1.5, 768-d) — same model the
+ * catalog narrower uses, so vectors share an embedding space across
+ * the workspace + catalog surfaces.
+ *
+ * Construction is lazy: the `EmbeddingClient` (and its env-key check)
+ * only fires when `embedBatch` is first called. A workspace that has
+ * no orbitals to bake never pays the cost or trips the missing-key
+ * error — useful for the memory-backed CLI runner that opens fresh
+ * workspaces without an API key.
+ */
+export declare function createDefaultEmbedder(): EmbedderPort;

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

@@ -0,0 +1,49 @@
+/**
+ * Fingerprint composition — pure functions that turn typed spec state
+ * into the short text strings the embedder hashes.
+ *
+ * Per the doc, orbital identity vectors stay small (~50-100 tokens)
+ * so they're stable under spec edits, while content/extraTrait
+ * fingerprints can grow more.
+ *
+ * @packageDocumentation
+ */
+import type { JsonObject } from '@almadar/core';
+/**
+ * Compose the orbital identity fingerprint from a spec.
+ *
+ * Pulls these typed fields off the spec (all optional — when missing
+ * the segment is omitted, never `undefined` interpolated):
+ *   - `orbitalName` (top-level on spec)
+ *   - `params.entityName`
+ *   - `organism`
+ *   - `params.extraTraits[].name` (or trait-name tail of ref if no
+ *     name) — included so renames + extras enter the identity surface
+ *
+ * The output is a single string with ` · ` separators; the embedder
+ * normalizes whitespace on its end.
+ */
+export declare function composeOrbitalIdentityFingerprint(spec: JsonObject): string;
+/**
+ * Compose the per-extraTraits[] entry fingerprint.
+ *
+ * Used both at bake time (for the sidecar's extraTraitIdentities[])
+ * and at query time (for the LLM-emitted entry being coerced). The
+ * shape MUST be identical on both sides so cosine geometry is
+ * meaningful — same fields in the same order.
+ */
+export declare function composeExtraTraitIdentityFingerprint(emit: {
+    ref: string;
+    name?: string;
+    linkedEntity?: string;
+}): string;
+/**
+ * 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.
+ */
+export declare function deriveExtraTraitAlias(emit: {
+    ref: string;
+    name?: string;
+}): string;

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

@@ -0,0 +1,39 @@
+/**
+ * `WorkspaceIndexImpl` — the runtime carrying the identity vectors per
+ * orbital + per extraTraits[] entry. Wires into the workspace's
+ * `SinkManager` to re-bake on each `kind: 'spec'` write; exposes the
+ * coercion methods `resolveOrbitalName` + `resolveTraitRef`.
+ *
+ * @packageDocumentation
+ */
+import type { JsonObject } from '@almadar/core';
+import type { WorkspaceBackend } from '../internal/types.js';
+import type { SinkManager } from '../internal/sink-manager.js';
+import type { EmbedderPort, ResolveOptions, ResolveResult, TraitRefEmit, WorkspaceIndex, WorkspaceIndexStats } from './types.js';
+export interface WorkspaceIndexDeps {
+    workDir: string;
+    backend: WorkspaceBackend;
+    sinks: SinkManager;
+    embedder: EmbedderPort;
+    listOrbitals: () => string[];
+    readSpec: (orbital: string) => JsonObject | null;
+}
+export declare class WorkspaceIndexImpl implements WorkspaceIndex {
+    private readonly deps;
+    private readonly entries;
+    /** Serialized re-bake per orbital so concurrent writeSpec events don't race. */
+    private readonly bakeQueue;
+    /** Names whose checksum doesn't match the current spec — surfaced via stats. */
+    private readonly stale;
+    constructor(deps: WorkspaceIndexDeps);
+    warm(): Promise<void>;
+    resolveOrbitalName(name: string, opts?: ResolveOptions): Promise<ResolveResult>;
+    resolveTraitRef(emit: TraitRefEmit, orbitalContext: {
+        orbitalName: string;
+    }, opts?: ResolveOptions): Promise<ResolveResult>;
+    stats(): WorkspaceIndexStats;
+    private rebakeOrbital;
+    private enqueueBake;
+    private bakeAndPersist;
+    private embedOne;
+}

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

@@ -0,0 +1,11 @@
+/**
+ * Public surface of the workspace index module. Re-exported from the
+ * top-level `@almadar/workspace` barrel.
+ *
+ * @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 { WorkspaceIndexImpl } from './index-impl.js';
+export type { WorkspaceIndexDeps } from './index-impl.js';
+export { createDefaultEmbedder } from './embedder.js';

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

@@ -0,0 +1,22 @@
+/**
+ * Sidecar I/O for per-orbital index entries.
+ *
+ * Reuses the workspace package's existing typed file helpers
+ * (`readJsonFile` + `writeJsonFile`) and path layout
+ * (`orbitalSessionFile`). No parallel file plumbing; no parallel path
+ * math.
+ *
+ * @packageDocumentation
+ */
+import type { JsonObject } from '@almadar/core';
+import type { WorkspaceBackend } from '../internal/types.js';
+import type { OrbitalIndexEntry } from './types.js';
+export declare function sidecarPath(workDir: string, orbital: string): string;
+export declare function readSidecar(backend: WorkspaceBackend, workDir: string, orbital: string): Promise<OrbitalIndexEntry | null>;
+export declare function writeSidecar(backend: WorkspaceBackend, workDir: string, orbital: string, entry: OrbitalIndexEntry): Promise<void>;
+/**
+ * SHA-256 over the JSON-stringified spec — the same content the
+ * sidecar's embeddings were computed from. Used to detect stale
+ * sidecars (spec changed since last bake → re-bake).
+ */
+export declare function checksumSpec(spec: JsonObject): string;

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

@@ -0,0 +1,132 @@
+/**
+ * Public types for the workspace index — Phase A of
+ * `docs/Almadar_Workspace_Index.md`. Identity vectors per orbital and
+ * per extraTraits[] entry, used for semantic coercion of LLM-emitted
+ * names back to canonical entities (R-10 orbital name drift + R-8
+ * duplicate-ref trait drift).
+ *
+ * @packageDocumentation
+ */
+import type { JsonObject } from '@almadar/core';
+/** Schema version baked into every sidecar; mismatch triggers re-bake. */
+export declare const WORKSPACE_INDEX_SCHEMA_VERSION: 1;
+/** Default coercion threshold per the doc's locked decision. */
+export declare const DEFAULT_COERCION_THRESHOLD: 0.85;
+/**
+ * Per-extraTraits[] entry identity vector. Baked alongside the orbital
+ * sidecar whenever the orbital's spec.json is written.
+ */
+export interface ExtraTraitIdentity {
+    /** Canonical ref of this entry (the key for coercion match). */
+    ref: string;
+    /** Entry's `name` rename, or trait-name tail of ref if no rename. */
+    alias: string;
+    /** Fingerprint text actually embedded — kept for debugging. */
+    fingerprint: string;
+    /** 768-d vector from bge-base-en-v1.5 (or whatever model the embedder uses). */
+    vector: readonly number[];
+}
+/**
+ * Per-orbital sidecar contents, persisted at
+ * `.almadar/sessions/<Orbital>/index.json` after every spec write.
+ */
+export interface OrbitalIndexEntry {
+    schemaVersion: typeof WORKSPACE_INDEX_SCHEMA_VERSION;
+    /** sha256 of the spec.json that produced this sidecar. */
+    specChecksum: string;
+    /** Orbital-level identity vector. */
+    identityVector: readonly number[];
+    /** Fingerprint text for the orbital identity vector — kept for debugging. */
+    identityFingerprint: string;
+    /** One per current `extraTraits[]` entry on this orbital. */
+    extraTraitIdentities: readonly ExtraTraitIdentity[];
+    /** 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).
+ */
+export interface WorkspaceIndexStats {
+    orbitalCount: number;
+    extraTraitIdentityCount: number;
+    staleOrbitals: readonly string[];
+}
+/**
+ * Public surface exposed via `WorkspaceService.index`.
+ */
+export interface WorkspaceIndex {
+    /**
+     * Walk every existing orbital, bake any missing or stale sidecars.
+     * Called synchronously by `openWorkspace` (strict cold start per the
+     * doc decision) so this is the authoritative point past which all
+     * subsequent queries return real data. Idempotent — re-baking an
+     * 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>;
+    /** Diagnostics surface. */
+    stats(): WorkspaceIndexStats;
+}
+/**
+ * Pluggable embedder — production wires `@almadar/llm`'s
+ * `EmbeddingClient`; tests inject a deterministic mock.
+ */
+export interface EmbedderPort {
+    /** Embed a batch of texts; returned vectors are in input order. */
+    embedBatch(texts: readonly string[]): Promise<{
+        embeddings: readonly (readonly number[])[];
+    }>;
+}
+/**
+ * JSON shape persisted at `.almadar/sessions/<Orbital>/index.json`.
+ * Mirrors `OrbitalIndexEntry` but with the JsonObject upper-bound the
+ * workspace's writeJsonFile helper requires.
+ */
+export type OrbitalIndexSidecar = OrbitalIndexEntry & JsonObject;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almadar/workspace",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "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",
@@ -26,6 +26,7 @@
   "license": "BUSL-1.1",
   "dependencies": {
     "@almadar/core": "^8.8.0",
+    "@almadar/llm": "^2.16.0",
     "typescript": "^5.4.0"
   },
   "devDependencies": {