@almadar/workspace 0.1.6 → 0.2.1

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

@@ -44,6 +44,8 @@ export declare function compiledDir(workDir: string): string;
 export declare function compiledFile(workDir: string, relPath: string): string;
 /** App marker — used internally by the resolver/factory. */
 export declare function appMarkerFile(workDir: string): string;
+/** Workspace-level index manifest path. */
+export declare function workspaceIndexManifestFile(workDir: string): string;
 /**
  * Resolve a user-supplied relative path within the sandbox. Rejects
  * absolute paths, `..` traversal, and any path that resolves outside

package/dist/types.d.ts

@@ -93,6 +93,9 @@ export type WorkspaceWriteEvent = {
     kind: 'workspace-index';
     orbital: string;
     content: JsonObject;
+} | {
+    kind: 'workspace-index-manifest';
+    content: JsonObject;
 };
 /**
  * Caller-supplied backend used when the local cache misses but the

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

@@ -0,0 +1,21 @@
+/**
+ * BM25 sparse retrieval — Phase B of the workspace-index.
+ *
+ * Tokenizes per-orbital spec.json into the term list the table indexes,
+ * builds a workspace-level inverted index, and scores free-form queries
+ * against it. Pure functions; no I/O.
+ *
+ * @packageDocumentation
+ */
+import type { JsonObject } from '@almadar/core';
+import type { BM25Table, BM25Options } from './types.js';
+/** Tokenize one spec.json into the set of terms BM25 indexes. */
+export declare function tokenizeSpec(spec: JsonObject): readonly string[];
+/** Build the workspace BM25 table from per-orbital token lists. */
+export declare function buildBM25Table(tokensPerOrbital: Readonly<Record<string, readonly string[]>>): BM25Table;
+/** Score every orbital in `table` against a free-form query string. */
+export declare function queryBM25(table: BM25Table, query: string, opts?: BM25Options): readonly {
+    orbital: string;
+    score: number;
+    matchedTokens: readonly string[];
+}[];

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

@@ -52,3 +52,28 @@ export declare function deriveExtraTraitAlias(emit: {
     ref: string;
     name?: string;
 }): string;
+/**
+ * Compose the orbital CONTENT fingerprint from a spec — the richer
+ * text the retrieval system embeds for prompt narrowing.
+ *
+ * Starts from the identity fingerprint then folds in every
+ * user-meaningful signal the spec carries:
+ *   - traitOverrides keys (the trait names being customized)
+ *   - traitOverrides.*.config.* values (the actual customizations
+ *     — discount percentages, labels, button text, chart types, etc.)
+ *   - entityFields[].name (the user's domain vocabulary)
+ *   - extraTraits[].name + tail-of-ref (added capabilities)
+ *   - ruleOverlay.rules[].capability values (compliance/audit signals)
+ *
+ * Order matters for token-position effects: identity first (so the
+ * embedder weights it heaviest), then the config values (the "what
+ * does it DO" signal), then entity + extra + rule tags.
+ *
+ * Per the design doc this is intentionally not catalog-filtered by
+ * `@tier === 'domain'` — that would require an @almadar/std dep from
+ * inside the workspace package. If retrieval-quality eval shows
+ * noise from internal-tier knobs polluting the fingerprint, the
+ * fix lands in a follow-up that brings the catalog metadata into
+ * reach (see plan B-Wave 0 notes).
+ */
+export declare function composeOrbitalContentFingerprint(spec: JsonObject): string;

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

@@ -0,0 +1,17 @@
+/**
+ * Graph builders — Phase C of the workspace-index.
+ *
+ * Pure walkers over typed inputs (spec.json batches, composed
+ * schema.orb text, params-history rows) that produce the hash-lookup
+ * maps the public Phase C surface serves.
+ *
+ * @packageDocumentation
+ */
+import type { JsonObject } from '@almadar/core';
+import type { ComposedMaps, IntentMaps, RecencyEntry } from './types.js';
+/** Per-orbital spec.json walker — derives the four intent maps. */
+export declare function buildIntentMaps(specs: Readonly<Record<string, JsonObject>>): IntentMaps;
+/** Composed schema.orb parser — derives event_name + composed entity_name maps. */
+export declare function buildComposedMaps(schemaOrbContent: string | null): ComposedMaps;
+/** Per-orbital params-history.jsonl tail walker — derives the recency map. */
+export declare function buildRecencyMap(history: Readonly<Record<string, readonly JsonObject[]>>): Readonly<Record<string, RecencyEntry>>;

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, ResolveOptions, ResolveResult, TraitRefEmit, WorkspaceIndex, WorkspaceIndexStats } from './types.js';
+import type { EmbedderPort, EntityBinding, EventEdge, RecentlyEditedOptions, ResolveOptions, ResolveResult, RetrievalOptions, RetrievalResult, RuleBinding, TraitRefEmit, WorkspaceIndex, WorkspaceIndexStats } from './types.js';
 export interface WorkspaceIndexDeps {
     workDir: string;
     backend: WorkspaceBackend;
@@ -17,6 +17,10 @@ export interface WorkspaceIndexDeps {
     embedder: EmbedderPort;
     listOrbitals: () => string[];
     readSpec: (orbital: string) => JsonObject | null;
+    /** Composed schema.orb content; null when missing or unparseable. */
+    readSchema: () => string | null;
+    /** Tail of params-history.jsonl rows for an orbital; empty array when none. */
+    readHistory: (orbital: string) => readonly JsonObject[];
 }
 export declare class WorkspaceIndexImpl implements WorkspaceIndex {
     private readonly deps;
@@ -25,13 +29,39 @@ export declare class WorkspaceIndexImpl implements WorkspaceIndex {
     private readonly bakeQueue;
     /** Names whose checksum doesn't match the current spec — surfaced via stats. */
     private readonly stale;
+    /** Cached spec.json per orbital so manifest rebuilds don't re-read disk. */
+    private readonly specsByOrbital;
+    /** Tokenized BM25 rows per orbital — rebuilt incrementally. */
+    private readonly tokensByOrbital;
+    /** Last-known recency timeline per orbital. */
+    private readonly recencyByOrbital;
+    /** Latest manifest payload (BM25 + intent + composed + recency). */
+    private manifest;
+    /** Serialized manifest writes so concurrent observer fires don't race. */
+    private manifestQueue;
     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[];
+    orbitalsListeningTo(event: string): readonly EventEdge[];
+    orbitalsEmitting(event: string): readonly EventEdge[];
+    orbitalsLinkedToEntity(entity: string): readonly EntityBinding[];
+    extraTraitImporters(refPath: string): readonly string[];
+    composedEvents(): readonly string[];
+    composedEntities(): readonly string[];
+    composedTraitRefPaths(): readonly string[];
+    rulesAppliedTo(entity: string): readonly RuleBinding[];
+    recentlyEdited(opts?: RecentlyEditedOptions): readonly string[];
+    private scheduleManifestRebuild;
+    private rebuildManifest;
+    private hydrateRecencyFromManifest;
+    private explainKnobMatches;
     private rebakeOrbital;
     private enqueueBake;
     private bakeAndPersist;

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

@@ -0,0 +1,13 @@
+/**
+ * Workspace-level manifest I/O for the BM25 token table + graph maps +
+ * recency. Mirrors `sidecar.ts` — same helpers (`readJsonFile` +
+ * `writeJsonFile`), same path-layout discipline. Parent dir `.almadar/`
+ * is created by `ensureSkeleton` at workspace open, so no mkdir here.
+ *
+ * @packageDocumentation
+ */
+import type { WorkspaceBackend } from '../internal/types.js';
+import type { WorkspaceIndexManifest } from './types.js';
+export declare function manifestPath(workDir: string): string;
+export declare function readManifest(backend: WorkspaceBackend, workDir: string): Promise<WorkspaceIndexManifest | null>;
+export declare function writeManifest(backend: WorkspaceBackend, workDir: string, manifest: WorkspaceIndexManifest): Promise<void>;

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

@@ -0,0 +1,17 @@
+/**
+ * Reciprocal Rank Fusion — combines arbitrary rankings into a single
+ * stable order. Key-agnostic; the workspace index uses orbital names.
+ *
+ * @packageDocumentation
+ */
+export interface RRFRankInput<TKey extends string> {
+    rankings: ReadonlyArray<readonly TKey[]>;
+}
+export interface RRFResult<TKey extends string> {
+    key: TKey;
+    score: number;
+    /** 1-based rank per input ranking; null when the key was absent from that ranking. */
+    ranks: readonly (number | null)[];
+}
+/** Reciprocal Rank Fusion. `k` defaults to `RRF_K` (60). */
+export declare function rrfFuse<TKey extends string>(rankings: ReadonlyArray<readonly TKey[]>, k?: number): readonly RRFResult<TKey>[];

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

@@ -8,10 +8,18 @@
  * @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;
+/** Schema version baked into every sidecar; mismatch triggers re-bake.
+ *  v1 — identity vector + extraTrait identity vectors only (Phase A).
+ *  v2 — adds contentVector + contentFingerprint for prompt-narrowing retrieval (Phase B).
+ *  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. */
+export declare const DEFAULT_RETRIEVAL_TOP_K: 3;
 /**
  * Per-extraTraits[] entry identity vector. Baked alongside the orbital
  * sidecar whenever the orbital's spec.json is written.
@@ -29,15 +37,32 @@ export interface ExtraTraitIdentity {
 /**
  * Per-orbital sidecar contents, persisted at
  * `.almadar/sessions/<Orbital>/index.json` after every spec write.
+ *
+ * Two dense vectors per orbital — DIFFERENT compositions, DIFFERENT
+ * invalidation cadence, DIFFERENT use:
+ *
+ *  - `identityVector` (Phase A) — small fingerprint over name + entity.
+ *    Stable across knob edits. Used by `resolveOrbitalName` for R-10
+ *    coercion.
+ *  - `contentVector` (Phase B) — richer fingerprint that ALSO folds
+ *    in every `traitOverrides.*.config.*` value, entityFields[].name,
+ *    extraTraits[].name + .ref tail, ruleOverlay rule capabilities.
+ *    Invalidates on every spec edit. Used by
+ *    `retrieveOrbitalsForPrompt` to rank orbitals against the user's
+ *    edit-prompt language.
  */
 export interface OrbitalIndexEntry {
     schemaVersion: typeof WORKSPACE_INDEX_SCHEMA_VERSION;
     /** sha256 of the spec.json that produced this sidecar. */
     specChecksum: string;
-    /** Orbital-level identity vector. */
+    /** Orbital-level identity vector (Phase A — R-10 coercion). */
     identityVector: readonly number[];
     /** Fingerprint text for the orbital identity vector — kept for debugging. */
     identityFingerprint: string;
+    /** Orbital-level content vector (Phase B — prompt narrowing). */
+    contentVector: readonly number[];
+    /** Fingerprint text for the content vector — kept for debugging. */
+    contentFingerprint: string;
     /** One per current `extraTraits[]` entry on this orbital. */
     extraTraitIdentities: readonly ExtraTraitIdentity[];
     /** Epoch ms at bake time — debugging only. */
@@ -111,6 +136,51 @@ export interface WorkspaceIndex {
     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
+     * Fusion (k=60), return top-K orbitals with explainability fields.
+     */
+    retrieveOrbitalsForPrompt(prompt: string, opts?: RetrievalOptions): Promise<readonly RetrievalResult[]>;
+    /** Phase B — sparse-only escape hatch. Tokenizes `query` and returns orbitals containing any term. */
+    findByToken(query: string): readonly string[];
+    /** Orbitals + traits whose state machine listens for `event`. */
+    orbitalsListeningTo(event: string): readonly EventEdge[];
+    /** Orbitals + traits whose state machine emits `event`. */
+    orbitalsEmitting(event: string): readonly EventEdge[];
+    /**
+     * Orbitals linked to `entity` — both composed (from the resolved
+     * schema.orb) and override-intent (from spec.json `linkedEntity`).
+     */
+    orbitalsLinkedToEntity(entity: string): readonly EntityBinding[];
+    /** Orbitals importing the trait at `refPath` via extraTraits[]. */
+    extraTraitImporters(refPath: string): readonly string[];
+    /**
+     * Every event name currently appearing in the composed schema as an
+     * emit or listen edge. Lets consumers feed each name back into
+     * `orbitalsEmitting` / `orbitalsListeningTo` to derive cross-orbital
+     * reactivity hints without holding a copy of the composed map.
+     */
+    composedEvents(): readonly string[];
+    /**
+     * Every entity name currently bound by the composed schema or by spec
+     * overrides. Lets consumers feed each name back into
+     * `orbitalsLinkedToEntity` without enumerating the composed map.
+     */
+    composedEntities(): readonly string[];
+    /**
+     * Every trait `refPath` currently imported via `extraTraits[]` across
+     * the workspace's per-orbital spec.json files. Lets consumers feed
+     * each back into `extraTraitImporters` for importer-set hints.
+     */
+    composedTraitRefPaths(): readonly string[];
+    /** Rules applied to `entity` via spec.json ruleOverlay.rules[]. */
+    rulesAppliedTo(entity: string): readonly RuleBinding[];
+    /**
+     * Orbitals edited within the last N turns (per
+     * params-history.jsonl). Ordered newest-first.
+     */
+    recentlyEdited(opts?: RecentlyEditedOptions): readonly string[];
     /** Diagnostics surface. */
     stats(): WorkspaceIndexStats;
 }
@@ -130,3 +200,136 @@ export interface EmbedderPort {
  * workspace's writeJsonFile helper requires.
  */
 export type OrbitalIndexSidecar = OrbitalIndexEntry & JsonObject;
+/**
+ * One orbital's tokenization row inside the BM25 table. `docLen` is the
+ * full token count (with repeats) — BM25's length normalization needs
+ * it. `termFreq` is the per-term count for cosine/IDF math.
+ */
+export interface BM25Document {
+    orbital: string;
+    termFreq: Readonly<Record<string, number>>;
+    docLen: number;
+}
+/**
+ * Workspace-level inverted-index payload. Persisted inside the index
+ * manifest at `.almadar/index.json`. Rebuilt incrementally per
+ * orbital — `documents` is the row store keyed by orbitalName.
+ */
+export interface BM25Table {
+    /** Per-orbital tokenization row. */
+    documents: Readonly<Record<string, BM25Document>>;
+    /**
+     * Document frequency — count of orbitals containing each term.
+     * Recomputed whenever `documents` changes (cheap; tens of orbitals).
+     */
+    docFreq: Readonly<Record<string, number>>;
+    /** Number of orbitals indexed (`Object.keys(documents).length`). */
+    docCount: number;
+    /** Sum(docLen) / docCount — BM25 needs this for length normalization. */
+    avgDocLen: number;
+}
+/** BM25 query options (Elastic defaults). */
+export interface BM25Options {
+    k1?: number;
+    b?: number;
+}
+export interface RetrievalOptions {
+    topK?: number;
+    rrfK?: number;
+    bm25?: BM25Options;
+}
+export interface RetrievalResult {
+    orbitalName: string;
+    /** RRF-fused score, monotonically decreasing across the returned array. */
+    score: number;
+    /**
+     * Tokens from the prompt that matched the orbital's BM25 row.
+     * Empty when this orbital surfaced via the dense leg only.
+     */
+    matchedTokens: readonly string[];
+    /**
+     * Domain knob keys (and their values) from the orbital's spec that the
+     * dense leg surfaced. Heuristic: knobs whose RENDERED text appears in
+     * the orbital's content fingerprint AND in the prompt verbatim.
+     * Empty when this orbital surfaced via the sparse leg only.
+     */
+    matchedKnobs: readonly string[];
+    /** 1-based rank within the dense ranking; `null` if not in the top-N dense list. */
+    rankByDense: number | null;
+    /** 1-based rank within the sparse ranking; `null` if not in the top-N sparse list. */
+    rankBySparse: number | null;
+}
+/** One emit/listen edge surfaced by the composed schema.orb. */
+export interface EventEdge {
+    orbital: string;
+    trait: string;
+    state?: string;
+    role: 'emit' | 'listen';
+    scope?: 'internal' | 'external';
+}
+/** One orbital→entity binding surfaced by either the composed schema or the user/agent's override intent. */
+export interface EntityBinding {
+    orbital: string;
+    trait: string;
+    source: 'composed' | 'override';
+}
+/** Rule applied to an entity, derived from spec.json ruleOverlay. */
+export interface RuleBinding {
+    orbital: string;
+    entityName: string;
+    capability: string;
+}
+/**
+ * Per-orbital recency entry. `turn` is monotonic across the workspace
+ * (rabit increments it on every coordinator turn). `lastChange` is
+ * epoch ms of the most recent params-history append.
+ */
+export interface RecencyEntry {
+    recencyTurn: number;
+    lastChange: number;
+}
+/**
+ * Maps derived ONLY from per-orbital spec.json. Rebuilt on each
+ * `kind: 'spec'` write for the affected orbital.
+ */
+export interface IntentMaps {
+    /** `entity_name → orbitals overriding linkedEntity`. */
+    entityNameOverrides: Readonly<Record<string, readonly EntityBinding[]>>;
+    /** `trait_ref_path → orbitals importing the trait`. */
+    traitRefImporters: Readonly<Record<string, readonly string[]>>;
+    /** `rule_capability → orbital-rule bindings`. */
+    ruleCapabilities: Readonly<Record<string, readonly RuleBinding[]>>;
+    /** `organism → orbitals`. */
+    organism: Readonly<Record<string, readonly string[]>>;
+}
+/**
+ * Maps derived ONLY from the composed schema.orb. Rebuilt on each
+ * `kind: 'schema'` write.
+ */
+export interface ComposedMaps {
+    /** `event_name → emit/listen edges`. */
+    events: Readonly<Record<string, readonly EventEdge[]>>;
+    /** `entity_name → composed entity bindings`. */
+    entityNameComposed: Readonly<Record<string, readonly EntityBinding[]>>;
+}
+/**
+ * Workspace-level manifest — combines BM25 table + intent maps + composed
+ * maps + recency. Persisted at `.almadar/index.json` and emitted via
+ * `WorkspaceWriteEvent.kind === 'workspace-index-manifest'` so consumer
+ * mirrors (apps/builder's Firestore observer) pick it up.
+ */
+export interface WorkspaceIndexManifest {
+    schemaVersion: typeof WORKSPACE_INDEX_SCHEMA_VERSION;
+    bm25: BM25Table;
+    intent: IntentMaps;
+    composed: ComposedMaps;
+    recency: Readonly<Record<string, RecencyEntry>>;
+    /** Epoch ms at last manifest write — debugging only. */
+    bakedAt: number;
+}
+/** JSON-persisted shape (intersection with JsonObject upper bound). */
+export type WorkspaceIndexManifestSidecar = WorkspaceIndexManifest & JsonObject;
+export interface RecentlyEditedOptions {
+    /** Return orbitals edited within the last N turns. Default: 5. */
+    withinTurns?: number;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almadar/workspace",
-  "version": "0.1.6",
+  "version": "0.2.1",
   "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",