@nusoft/nuos-build-catalogue 0.10.0 → 0.10.2

package/dist/commands/write.js

@@ -0,0 +1,247 @@
+/**
+ * Phase H part 2 — flag-driven write commands.
+ *
+ * Each handler:
+ *   1. Validates the flags
+ *   2. Looks up the target record from the store
+ *   3. Builds a typed `CaptureInput` for the relevant workflow
+ *   4. Drives the NuFlow lifecycle through the runtime
+ *   5. Reports the result
+ *
+ * No interactive prompts; flag-driven only. Interactive `create`
+ * commands are deferred (Phase H part 3).
+ */
+import { normaliseHandle } from './handlers.js';
+import { extractForCompletion } from '../runtime/ac-parse.js';
+const BUILD_MAINTAINER = {
+    kind: 'staff',
+    id: 'build-maintainer',
+    role: 'build-maintainer',
+};
+// ---------------------------------------------------------------------------
+// wu advance <handle> --to=<status> [--reason="..."]
+// ---------------------------------------------------------------------------
+export async function cmdWuAdvance(store, runtime, args) {
+    if (!args.handle) {
+        return { output: 'Usage: nuos-catalogue wu advance <handle> --to=<status> [--reason="..."]', exitCode: 2 };
+    }
+    if (!args.to) {
+        return { output: '--to=<status> is required (e.g. --to=in_progress)', exitCode: 2 };
+    }
+    const handle = normaliseHandle('work_unit', args.handle);
+    const record = store.get(handle);
+    if (!record || record.register !== 'work_unit') {
+        return { output: `no work_unit record for handle "${handle}"`, exitCode: 1 };
+    }
+    const fromStatus = inferWorkflowStatus(record);
+    // For → completed, the pack's completion gate requires the AC list.
+    // Extract it from the markdown so the gate can verify every AC is
+    // ticked-with-evidence. For other transitions the AC list is informational.
+    const acceptanceCriteria = args.to === 'completed' ? extractForCompletion(record.rawMarkdown) : undefined;
+    const capture = {
+        channel: 'typed_note',
+        content: `advance ${handle} → ${args.to}${args.reason ? `: ${args.reason}` : ''}`,
+        subjects: [{ kind: 'work_unit', id: handle }],
+        metadata: {
+            targetHandle: handle,
+            fromStatus,
+            toStatus: args.to,
+            reason: args.reason,
+            acceptanceCriteria,
+        },
+    };
+    return await driveLifecycle(runtime, 'work_unit.advance_status', capture, handle, args.to);
+}
+function inferWorkflowStatus(record) {
+    // Strip emoji + leading/trailing whitespace from the stored status text.
+    const raw = (record.status ?? '').trim();
+    // Pull the first ASCII word that matches a known status enum.
+    const KNOWN = [
+        'proposed',
+        'ready',
+        'in_progress',
+        'in_review',
+        'completed',
+        'superseded',
+        'cancelled',
+        'deferred-with-trigger',
+        'blocked-on-question',
+        'in_flight',
+        'in flight',
+        'blocked',
+    ];
+    const lower = raw.toLowerCase();
+    for (const candidate of KNOWN) {
+        if (lower.includes(candidate)) {
+            // Normalise variants we accept on input but don't have in the
+            // pack's state machine.
+            if (candidate === 'in_flight' || candidate === 'in flight')
+                return 'in_progress';
+            if (candidate === 'blocked')
+                return 'blocked-on-question';
+            return candidate;
+        }
+    }
+    return 'proposed';
+}
+// ---------------------------------------------------------------------------
+// wu tick <handle> --index=N --evidence="..."
+// ---------------------------------------------------------------------------
+export async function cmdWuTick(store, runtime, args) {
+    if (!args.handle) {
+        return {
+            output: 'Usage: nuos-catalogue wu tick <handle> --index=N --evidence="..."',
+            exitCode: 2,
+        };
+    }
+    if (typeof args.index !== 'number' || !Number.isInteger(args.index) || args.index < 0) {
+        return { output: '--index=<non-negative integer> is required', exitCode: 2 };
+    }
+    if (!args.evidence || args.evidence.trim().length === 0) {
+        return { output: '--evidence="..." is required (non-empty)', exitCode: 2 };
+    }
+    const handle = normaliseHandle('work_unit', args.handle);
+    if (!store.has(handle)) {
+        return { output: `no work_unit record for handle "${handle}"`, exitCode: 1 };
+    }
+    const capture = {
+        channel: 'typed_note',
+        content: `tick AC #${args.index} on ${handle}`,
+        subjects: [{ kind: 'work_unit', id: handle }],
+        metadata: {
+            targetHandle: handle,
+            criterionIndex: args.index,
+            evidence: args.evidence,
+        },
+    };
+    return await driveLifecycle(runtime, 'work_unit.tick_acceptance_criterion', capture, handle, `index ${args.index}`);
+}
+// ---------------------------------------------------------------------------
+// decision supersede <target> --by=<superseding> [--reason="..."]
+// ---------------------------------------------------------------------------
+export async function cmdDecisionSupersede(store, runtime, args) {
+    if (!args.target) {
+        return {
+            output: 'Usage: nuos-catalogue decision supersede <target> --by=<superseding> [--reason="..."]',
+            exitCode: 2,
+        };
+    }
+    if (!args.by) {
+        return { output: '--by=<superseding D-handle> is required', exitCode: 2 };
+    }
+    const target = normaliseHandle('decision', args.target);
+    const superseding = normaliseHandle('decision', args.by);
+    const targetRecord = store.get(target);
+    const supersedingRecord = store.get(superseding);
+    if (!targetRecord || targetRecord.register !== 'decision') {
+        return { output: `no decision record for target "${target}"`, exitCode: 1 };
+    }
+    if (!supersedingRecord || supersedingRecord.register !== 'decision') {
+        return { output: `no decision record for superseding "${superseding}"`, exitCode: 1 };
+    }
+    const capture = {
+        channel: 'typed_note',
+        content: `supersede ${target} by ${superseding}`,
+        subjects: [
+            { kind: 'decision', id: target },
+            { kind: 'decision', id: superseding },
+        ],
+        metadata: {
+            targetHandle: target,
+            supersedingHandle: superseding,
+            // Workflow validates this matches; we infer from the stored status.
+            // For decisions we assume the target is currently 'accepted' unless
+            // the markdown says otherwise; the workflow rejects invalid input.
+            targetCurrentStatus: 'accepted',
+            reason: args.reason,
+        },
+    };
+    return await driveLifecycle(runtime, 'decision.supersede', capture, target, superseding);
+}
+// ---------------------------------------------------------------------------
+// question resolve <q-handle> --by=<d-handle> [--reason="..."]
+// ---------------------------------------------------------------------------
+export async function cmdQuestionResolve(store, runtime, args) {
+    if (!args.qHandle) {
+        return {
+            output: 'Usage: nuos-catalogue question resolve <q-handle> --by=<d-handle> [--reason="..."]',
+            exitCode: 2,
+        };
+    }
+    if (!args.by) {
+        return { output: '--by=<resolving D-handle> is required', exitCode: 2 };
+    }
+    const qHandle = normaliseHandle('open_question', args.qHandle);
+    const dHandle = normaliseHandle('decision', args.by);
+    const qRecord = store.get(qHandle);
+    const dRecord = store.get(dHandle);
+    if (!qRecord || qRecord.register !== 'open_question') {
+        return { output: `no open_question record for handle "${qHandle}"`, exitCode: 1 };
+    }
+    if (!dRecord || dRecord.register !== 'decision') {
+        return { output: `no decision record for resolving handle "${dHandle}"`, exitCode: 1 };
+    }
+    const capture = {
+        channel: 'typed_note',
+        content: `resolve ${qHandle} by ${dHandle}`,
+        subjects: [
+            { kind: 'open_question', id: qHandle },
+            { kind: 'decision', id: dHandle },
+        ],
+        metadata: {
+            targetHandle: qHandle,
+            targetCurrentStatus: 'active',
+            resolvingDecisionHandle: dHandle,
+            reason: args.reason,
+        },
+    };
+    return await driveLifecycle(runtime, 'open_question.resolve', capture, qHandle, dHandle);
+}
+// ---------------------------------------------------------------------------
+// Lifecycle driver — single path that handles all four workflows
+// ---------------------------------------------------------------------------
+async function driveLifecycle(runtime, workflowType, capture, primarySubject, detail) {
+    let workflow;
+    try {
+        workflow = await runtime.startWorkflow(workflowType, BUILD_MAINTAINER, capture);
+    }
+    catch (err) {
+        return {
+            output: `${workflowType} rejected at start: ${err.message}`,
+            exitCode: 1,
+        };
+    }
+    if (workflow.status === 'waiting_for_clarification') {
+        return {
+            output: `${workflowType} produced a clarification request: ${workflow.clarification?.reason ?? 'unspecified'}`,
+            exitCode: 1,
+        };
+    }
+    if (workflow.status !== 'waiting_for_confirmation') {
+        return {
+            output: `${workflowType} unexpected post-start status: ${workflow.status}`,
+            exitCode: 1,
+        };
+    }
+    workflow = await runtime.confirmIntent(workflow.id, BUILD_MAINTAINER.id);
+    if (workflow.status === 'waiting_for_approval') {
+        workflow = await runtime.approveIntent(workflow.id, BUILD_MAINTAINER.id);
+    }
+    if (workflow.status !== 'committing') {
+        return {
+            output: `${workflowType} unexpected pre-commit status: ${workflow.status}`,
+            exitCode: 1,
+        };
+    }
+    workflow = await runtime.commitIntent(workflow.id, BUILD_MAINTAINER.id);
+    if (workflow.status !== 'completed') {
+        return {
+            output: `${workflowType} commit failed: status=${workflow.status}`,
+            exitCode: 1,
+        };
+    }
+    return {
+        output: `${workflowType} ✅ ${primarySubject} → ${detail}  (commit ${workflow.commitRef?.commitRef ?? '?'})`,
+        exitCode: 0,
+    };
+}

package/dist/embedder/ollama.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Ollama embedder — local inference, no network egress.
+ *
+ * Default model: qwen3-embedding:8b (4096 dims, 32k context). Config via
+ * NUOS_CATALOGUE_OLLAMA_MODEL. Smaller variants (qwen3-embedding:4b,
+ * qwen3-embedding:0.6b) work the same way; switching variants requires
+ * a full reindex if the dimension changes.
+ *
+ * Why local: keeps the catalogue's content (and any future workload that
+ * uses the same Embedder interface) inside whatever boundary Ollama is
+ * running in — typically the developer's machine, or a school-local
+ * server in a deployment context. Closes one of the two remaining
+ * third-party calls in the NuOS stack (the other is LLM completion;
+ * WU 058 covers that).
+ *
+ * **Unload-after-use commitment.** A school server (or developer
+ * machine) must not be left holding ~5GB of model in RAM idle. Per the
+ * NuOS-wide local-inference principle, models are loaded for the
+ * duration of work and unloaded as soon as the work is done.
+ *
+ * Implementation: each call passes `keep_alive: "1m"` so sequential
+ * batches within one operation stay warm; the embedder exposes
+ * `dispose()` which explicitly unloads via `keep_alive: 0`. The CLI
+ * calls `dispose()` after every `index` and `search` command. If the
+ * process exits without `dispose()` (crash, kill -9), Ollama's own
+ * idle-timeout (the keep_alive: "1m" we sent) cleans up within a
+ * minute.
+ *
+ * Sizing note — the 8b model at Q4_K_M is ~4.7GB on disk and benefits
+ * from ~16GB of RAM. Apple Silicon Metal acceleration helps a lot. On
+ * smaller boxes drop to qwen3-embedding:4b (better accuracy/RAM ratio)
+ * or qwen3-embedding:0.6b (CPU-only friendly).
+ */
+import type { Embedder } from './types.js';
+export declare class OllamaEmbedder implements Embedder {
+    readonly dimensions: number;
+    readonly modelId: string;
+    private readonly host;
+    private readonly batchSize;
+    private constructor();
+    static fromEnv(): Promise<OllamaEmbedder>;
+    embed(texts: string[]): Promise<Float32Array[]>;
+    private embedBatch;
+    /**
+     * Explicitly unload the model from Ollama's RAM. Safe to call multiple
+     * times; safe to call before any embed() — it's a no-op if the model
+     * isn't currently loaded.
+     *
+     * Implements the NuOS-wide unload-after-use commitment: at the end of
+     * any operation that uses local inference, the model is freed so the
+     * host machine isn't left carrying idle weights.
+     */
+    dispose(): Promise<void>;
+}

package/dist/embedder/ollama.js

@@ -0,0 +1,164 @@
+/**
+ * Ollama embedder — local inference, no network egress.
+ *
+ * Default model: qwen3-embedding:8b (4096 dims, 32k context). Config via
+ * NUOS_CATALOGUE_OLLAMA_MODEL. Smaller variants (qwen3-embedding:4b,
+ * qwen3-embedding:0.6b) work the same way; switching variants requires
+ * a full reindex if the dimension changes.
+ *
+ * Why local: keeps the catalogue's content (and any future workload that
+ * uses the same Embedder interface) inside whatever boundary Ollama is
+ * running in — typically the developer's machine, or a school-local
+ * server in a deployment context. Closes one of the two remaining
+ * third-party calls in the NuOS stack (the other is LLM completion;
+ * WU 058 covers that).
+ *
+ * **Unload-after-use commitment.** A school server (or developer
+ * machine) must not be left holding ~5GB of model in RAM idle. Per the
+ * NuOS-wide local-inference principle, models are loaded for the
+ * duration of work and unloaded as soon as the work is done.
+ *
+ * Implementation: each call passes `keep_alive: "1m"` so sequential
+ * batches within one operation stay warm; the embedder exposes
+ * `dispose()` which explicitly unloads via `keep_alive: 0`. The CLI
+ * calls `dispose()` after every `index` and `search` command. If the
+ * process exits without `dispose()` (crash, kill -9), Ollama's own
+ * idle-timeout (the keep_alive: "1m" we sent) cleans up within a
+ * minute.
+ *
+ * Sizing note — the 8b model at Q4_K_M is ~4.7GB on disk and benefits
+ * from ~16GB of RAM. Apple Silicon Metal acceleration helps a lot. On
+ * smaller boxes drop to qwen3-embedding:4b (better accuracy/RAM ratio)
+ * or qwen3-embedding:0.6b (CPU-only friendly).
+ */
+const DEFAULT_MODEL = 'qwen3-embedding:8b';
+const DEFAULT_HOST = 'http://localhost:11434';
+// Qwen3-Embedding produces Matryoshka representations 32–4096 dims.
+// We use the model default. A future tweak could truncate to e.g. 1024
+// to shrink the index by 4x at minor accuracy cost.
+const KNOWN_DIMENSIONS = {
+    'qwen3-embedding:8b': 4096,
+    'qwen3-embedding:4b': 2560,
+    'qwen3-embedding:0.6b': 1024,
+};
+export class OllamaEmbedder {
+    dimensions;
+    modelId;
+    host;
+    batchSize;
+    constructor(options) {
+        this.modelId = options.modelId;
+        this.dimensions = options.dimensions;
+        this.host = options.host;
+        this.batchSize = options.batchSize;
+    }
+    static async fromEnv() {
+        const modelId = process.env.NUOS_CATALOGUE_OLLAMA_MODEL ?? DEFAULT_MODEL;
+        const host = (process.env.OLLAMA_HOST ?? DEFAULT_HOST).replace(/\/$/, '');
+        const batchSize = Number(process.env.NUOS_CATALOGUE_OLLAMA_BATCH ?? 8);
+        // Probe the host to give a useful error early
+        let dimensions = KNOWN_DIMENSIONS[modelId];
+        try {
+            const probe = await fetch(`${host}/api/embed`, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({ model: modelId, input: 'probe' }),
+            });
+            if (!probe.ok) {
+                const body = await probe.text().catch(() => '<unreadable>');
+                throw new Error(`Ollama probe failed (${probe.status}): ${body}\n` +
+                    `Check that Ollama is running and the model is pulled:\n` +
+                    `  ollama serve\n` +
+                    `  ollama pull ${modelId}`);
+            }
+            const json = (await probe.json());
+            const probeDim = json.embeddings?.[0]?.length;
+            if (probeDim) {
+                if (dimensions && dimensions !== probeDim) {
+                    // Trust the live probe over the lookup table
+                    dimensions = probeDim;
+                }
+                dimensions ??= probeDim;
+            }
+        }
+        catch (err) {
+            if (err instanceof Error && err.message.startsWith('Ollama probe failed'))
+                throw err;
+            throw new Error(`Could not reach Ollama at ${host}. Is it running? ` +
+                `Start it with \`ollama serve\` and pull the model with \`ollama pull ${modelId}\`. ` +
+                `Underlying error: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        if (!dimensions) {
+            throw new Error(`Could not determine embedding dimension for model ${modelId}. ` +
+                `If this is a new variant, add it to KNOWN_DIMENSIONS in src/embedder/ollama.ts.`);
+        }
+        return new OllamaEmbedder({ modelId, dimensions, host, batchSize });
+    }
+    async embed(texts) {
+        if (texts.length === 0)
+            return [];
+        const out = [];
+        for (let i = 0; i < texts.length; i += this.batchSize) {
+            const slice = texts.slice(i, i + this.batchSize);
+            const embeddings = await this.embedBatch(slice);
+            out.push(...embeddings);
+        }
+        return out;
+    }
+    async embedBatch(texts) {
+        const res = await fetch(`${this.host}/api/embed`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({
+                model: this.modelId,
+                input: texts,
+                // Keep the model warm only for the duration of one operation.
+                // dispose() at the end of the run sends keep_alive: 0 to unload.
+                keep_alive: '1m',
+            }),
+        });
+        if (!res.ok) {
+            const body = await res.text().catch(() => '<unreadable>');
+            throw new Error(`Ollama embed call failed (${res.status}): ${body}`);
+        }
+        const json = (await res.json());
+        if (!Array.isArray(json.embeddings) || json.embeddings.length !== texts.length) {
+            throw new Error(`Ollama returned ${json.embeddings?.length ?? 0} embeddings for ${texts.length} inputs`);
+        }
+        return json.embeddings.map((e) => new Float32Array(e));
+    }
+    /**
+     * Explicitly unload the model from Ollama's RAM. Safe to call multiple
+     * times; safe to call before any embed() — it's a no-op if the model
+     * isn't currently loaded.
+     *
+     * Implements the NuOS-wide unload-after-use commitment: at the end of
+     * any operation that uses local inference, the model is freed so the
+     * host machine isn't left carrying idle weights.
+     */
+    async dispose() {
+        try {
+            const res = await fetch(`${this.host}/api/embed`, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                // Empty input + keep_alive: 0 is Ollama's documented unload trigger.
+                body: JSON.stringify({
+                    model: this.modelId,
+                    input: '',
+                    keep_alive: 0,
+                }),
+            });
+            // Non-2xx is non-fatal — the keep_alive on prior calls will still
+            // expire within ~1 minute and Ollama will free the model.
+            if (!res.ok) {
+                const body = await res.text().catch(() => '<unreadable>');
+                process.stderr.write(`[ollama] dispose() returned ${res.status}; model will unload via keep_alive timeout. body: ${body}\n`);
+            }
+        }
+        catch (err) {
+            // Network error reaching Ollama at dispose time is non-fatal.
+            // The keep_alive timeout on prior calls covers cleanup.
+            process.stderr.write(`[ollama] dispose() failed: ${err instanceof Error ? err.message : String(err)}\n`);
+        }
+    }
+}

package/dist/embedder/openai.d.ts

@@ -0,0 +1,21 @@
+/**
+ * OpenAI embedder — text-embedding-3-small (1536 dims).
+ *
+ * Auth: OPENAI_API_KEY env var.
+ *
+ * Chosen as the alternate embedder because it has the lowest setup
+ * friction for a contributor without GCP access. Per the WU 110 spec
+ * the build catalogue is non-sensitive so cross-region inference is
+ * acceptable; per D010 NuVector does not generate embeddings so the
+ * consumer (this CLI) decides.
+ */
+import type { Embedder } from './types.js';
+export declare class OpenAIEmbedder implements Embedder {
+    private readonly apiKey;
+    readonly dimensions = 1536;
+    readonly modelId = "text-embedding-3-small";
+    constructor(apiKey: string);
+    static fromEnv(): OpenAIEmbedder;
+    embed(texts: string[]): Promise<Float32Array[]>;
+    dispose(): Promise<void>;
+}

package/dist/embedder/openai.js

@@ -0,0 +1,56 @@
+/**
+ * OpenAI embedder — text-embedding-3-small (1536 dims).
+ *
+ * Auth: OPENAI_API_KEY env var.
+ *
+ * Chosen as the alternate embedder because it has the lowest setup
+ * friction for a contributor without GCP access. Per the WU 110 spec
+ * the build catalogue is non-sensitive so cross-region inference is
+ * acceptable; per D010 NuVector does not generate embeddings so the
+ * consumer (this CLI) decides.
+ */
+const MODEL_ID = 'text-embedding-3-small';
+const DIMENSIONS = 1536;
+const API_URL = 'https://api.openai.com/v1/embeddings';
+export class OpenAIEmbedder {
+    apiKey;
+    dimensions = DIMENSIONS;
+    modelId = MODEL_ID;
+    constructor(apiKey) {
+        this.apiKey = apiKey;
+    }
+    static fromEnv() {
+        const key = process.env.OPENAI_API_KEY;
+        if (!key) {
+            throw new Error('OPENAI_API_KEY is not set; required for the openai embedder. ' +
+                'Set it, or switch to NUOS_CATALOGUE_EMBEDDER=vertex.');
+        }
+        return new OpenAIEmbedder(key);
+    }
+    async embed(texts) {
+        if (texts.length === 0)
+            return [];
+        const res = await fetch(API_URL, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                authorization: `Bearer ${this.apiKey}`,
+            },
+            body: JSON.stringify({
+                model: MODEL_ID,
+                input: texts,
+                encoding_format: 'float',
+            }),
+        });
+        if (!res.ok) {
+            const body = await res.text().catch(() => '<unreadable body>');
+            throw new Error(`OpenAI embeddings call failed (${res.status}): ${body}`);
+        }
+        const json = (await res.json());
+        // Sort by index because the API does not guarantee response order
+        const sorted = [...json.data].sort((a, b) => a.index - b.index);
+        return sorted.map((d) => new Float32Array(d.embedding));
+    }
+    // Cloud embedder — nothing to release on the local machine.
+    async dispose() { }
+}

package/dist/embedder/select.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Embedder selector — reads NUOS_CATALOGUE_EMBEDDER from env.
+ *
+ * Default: ollama (local inference; no network egress; sovereignty by
+ * default). Alternatives: vertex (cloud Google), openai (cloud OpenAI),
+ * stub (deterministic hash for tests).
+ */
+import type { Embedder } from './types.js';
+export declare function selectEmbedderFromEnv(): Promise<Embedder>;

package/dist/embedder/select.js

@@ -0,0 +1,27 @@
+/**
+ * Embedder selector — reads NUOS_CATALOGUE_EMBEDDER from env.
+ *
+ * Default: ollama (local inference; no network egress; sovereignty by
+ * default). Alternatives: vertex (cloud Google), openai (cloud OpenAI),
+ * stub (deterministic hash for tests).
+ */
+import { OllamaEmbedder } from './ollama.js';
+import { VertexEmbedder } from './vertex.js';
+import { OpenAIEmbedder } from './openai.js';
+import { StubEmbedder } from './stub.js';
+export async function selectEmbedderFromEnv() {
+    const name = (process.env.NUOS_CATALOGUE_EMBEDDER ?? 'ollama').toLowerCase();
+    switch (name) {
+        case 'ollama':
+            return OllamaEmbedder.fromEnv();
+        case 'vertex':
+            return VertexEmbedder.fromEnv();
+        case 'openai':
+            return OpenAIEmbedder.fromEnv();
+        case 'stub':
+            return new StubEmbedder();
+        default:
+            throw new Error(`Unknown embedder "${name}" (NUOS_CATALOGUE_EMBEDDER). ` +
+                `Use ollama | vertex | openai | stub.`);
+    }
+}

package/dist/embedder/stub.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Deterministic hash-based embedder for tests.
+ *
+ * Not for production retrieval — but lets the indexer + search pipeline
+ * be exercised end-to-end without an API key. Enabled via
+ * NUOS_CATALOGUE_EMBEDDER=stub.
+ */
+import type { Embedder } from './types.js';
+export declare class StubEmbedder implements Embedder {
+    readonly dimensions = 384;
+    readonly modelId = "stub-sha256-bag-of-words";
+    embed(texts: string[]): Promise<Float32Array[]>;
+    private embedOne;
+    dispose(): Promise<void>;
+}

package/dist/embedder/stub.js

@@ -0,0 +1,40 @@
+/**
+ * Deterministic hash-based embedder for tests.
+ *
+ * Not for production retrieval — but lets the indexer + search pipeline
+ * be exercised end-to-end without an API key. Enabled via
+ * NUOS_CATALOGUE_EMBEDDER=stub.
+ */
+import { createHash } from 'node:crypto';
+const DIMENSIONS = 384;
+export class StubEmbedder {
+    dimensions = DIMENSIONS;
+    modelId = 'stub-sha256-bag-of-words';
+    async embed(texts) {
+        return texts.map((t) => this.embedOne(t));
+    }
+    embedOne(text) {
+        const out = new Float32Array(DIMENSIONS);
+        const tokens = text.toLowerCase().split(/[^a-z0-9]+/u).filter(Boolean);
+        for (const tok of tokens) {
+            const h = createHash('sha256').update(tok).digest();
+            // Spread the token across 4 dims using the first 8 hash bytes
+            for (let i = 0; i < 4; i++) {
+                const idx = h.readUInt16BE(i * 2) % DIMENSIONS;
+                out[idx] += 1;
+            }
+        }
+        // L2 normalise
+        let norm = 0;
+        for (let i = 0; i < DIMENSIONS; i++)
+            norm += out[i] * out[i];
+        norm = Math.sqrt(norm);
+        if (norm > 0) {
+            for (let i = 0; i < DIMENSIONS; i++)
+                out[i] /= norm;
+        }
+        return out;
+    }
+    // No-op — stub holds no resources.
+    async dispose() { }
+}

package/dist/embedder/types.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Embedder interface — per D010, NuVector does not generate embeddings;
+ * the consumer supplies them. The catalogue indexer ships its own
+ * embedder implementations and routes via this interface.
+ */
+export interface Embedder {
+    embed(texts: string[]): Promise<Float32Array[]>;
+    /**
+     * Release any resources the embedder is holding. For local-inference
+     * embedders this unloads the model from RAM. For cloud embedders this
+     * is a no-op. Always called by the CLI at the end of an operation per
+     * the NuOS-wide unload-after-use commitment.
+     */
+    dispose(): Promise<void>;
+    readonly dimensions: number;
+    readonly modelId: string;
+}
+export type EmbedderName = 'ollama' | 'vertex' | 'openai' | 'stub';
+export interface EmbedderConfig {
+    name: EmbedderName;
+}

package/dist/embedder/types.js

@@ -0,0 +1,6 @@
+/**
+ * Embedder interface — per D010, NuVector does not generate embeddings;
+ * the consumer supplies them. The catalogue indexer ships its own
+ * embedder implementations and routes via this interface.
+ */
+export {};