@ai-sdlc/orchestrator 0.10.0 → 0.13.0

package/dist/embedding/pipeline-load.js

@@ -0,0 +1,178 @@
+/**
+ * Pipeline-load wiring for RFC-0019 §10.1 / Phase 4 (AISDLC-340).
+ *
+ * Resolves `Pipeline.spec.embedding` → adapter (via registry) + storage
+ * backend (via factory). This is the single entry point pipeline loaders
+ * call when constructing the embedding substrate for a pipeline run.
+ *
+ * Feature-flag semantics:
+ *   AI_SDLC_EMBEDDING_PROVIDER=on    → load per spec
+ *   anything else / unset            → return null (framework disabled)
+ *
+ * When the flag is off AND a spec is present, callers SHOULD log a
+ * warning so misconfiguration is visible — done here via the optional
+ * `onFlagOffWithSpec` callback so the orchestrator can route the
+ * warning through its own logging surface (events.jsonl, console, etc.).
+ *
+ * Errors:
+ *   - Unknown adapter name → `UnknownEmbeddingProvider`
+ *   - Unknown storage backend → bare `Error` from the storage factory
+ *   - Adapter is deprecated/removed → re-thrown from the deprecation
+ *     gate; pipeline-load aborts so operators see the failure at load
+ *     time, not at first embed().
+ *
+ * Tests: `pipeline-load.test.ts`
+ */
+import { getEmbeddingAdapter } from './registry.js';
+import { createEmbeddingStorageBackend } from './storage/index.js';
+import { EmbeddingModelDeprecated, EmbeddingModelDeprecating, EmbeddingModelRemoved, } from './errors.js';
+/** Default values applied when fields are omitted from the spec. */
+export const EMBEDDING_DEFAULTS = {
+    storageBackend: 'jsonl',
+    staleVectorPolicy: 'lazy-re-embed',
+    autoEmbedOnWrite: true,
+    maxBatchSize: 2048,
+    /** Framework default; adapter MAY declare a different defaultGracePeriodDays. */
+    gracePeriodDays: 90,
+};
+/**
+ * `AI_SDLC_EMBEDDING_PROVIDER` flag parser. Mirrors the
+ * `AI_SDLC_DEPS_COMPOSITION` and `AI_SDLC_AUTONOMOUS_ORCHESTRATOR` patterns:
+ * truthy = `1|true|yes|on` (case-insensitive); anything else (including
+ * unset) is OFF.
+ */
+export function isEmbeddingFrameworkEnabled(env = process.env) {
+    const raw = env.AI_SDLC_EMBEDDING_PROVIDER;
+    if (!raw)
+        return false;
+    return ['1', 'true', 'yes', 'on'].includes(raw.toLowerCase());
+}
+/**
+ * Resolve `(adapter, storage, policy)` from a pipeline spec.
+ *
+ * Returns `null` when the framework is disabled — by feature flag OR by
+ * absent spec. Callers SHOULD treat null as "no embedding substrate
+ * available" and let consumers emit `EmbeddingProviderNotConfigured`.
+ *
+ * Throws on:
+ *   - unknown adapter (`UnknownEmbeddingProvider`)
+ *   - unknown storage backend (bare `Error`)
+ *   - adapter past `removedAt` (`EmbeddingModelRemoved`)
+ *   - adapter past `deprecatedAt` in strict mode (`EmbeddingModelDeprecated`)
+ *
+ * @example
+ *   const substrate = loadEmbeddingFromPipelineSpec(
+ *     pipeline.spec.embedding,
+ *     { artifactsDir: '/repo/.ai-sdlc/artifacts' },
+ *   );
+ *   if (substrate) {
+ *     const vec = await substrate.adapter.embed('hello', 'rfc-0009-tessellation-drift');
+ *     await substrate.storage.write({ ... });
+ *   }
+ */
+export function loadEmbeddingFromPipelineSpec(spec, options = {}) {
+    if (!spec) {
+        return null;
+    }
+    if (!isEmbeddingFrameworkEnabled()) {
+        options.onFlagOffWithSpec?.(spec);
+        return null;
+    }
+    const adapter = getEmbeddingAdapter(spec.provider);
+    // Deprecation gate. Strict mode FAILs at deprecatedAt; default mode
+    // continues to warn until removedAt (RFC-0019 OQ-4 re-walkthrough).
+    const now = options.now ?? new Date();
+    enforceDeprecationGate(adapter, spec, now, options.onDeprecationWarning);
+    // Resolve fallback (when distinct). Fallback failures don't block
+    // load — they surface at runtime when the primary is unavailable.
+    let fallbackAdapter;
+    if (spec.fallback && spec.fallback !== spec.provider) {
+        fallbackAdapter = getEmbeddingAdapter(spec.fallback);
+    }
+    const artifactsDir = options.artifactsDir ?? process.env.ARTIFACTS_DIR ?? '.ai-sdlc/artifacts';
+    const storage = createEmbeddingStorageBackend(spec.storageBackend ?? EMBEDDING_DEFAULTS.storageBackend, artifactsDir);
+    return {
+        adapter,
+        fallbackAdapter,
+        storage,
+        staleVectorPolicy: spec.staleVectorPolicy ?? EMBEDDING_DEFAULTS.staleVectorPolicy,
+        autoEmbedOnWrite: spec.autoEmbedOnWrite ?? EMBEDDING_DEFAULTS.autoEmbedOnWrite,
+        maxBatchSize: spec.maxBatchSize ?? EMBEDDING_DEFAULTS.maxBatchSize,
+    };
+}
+/**
+ * Three-layer precedence per OQ-4 re-walkthrough:
+ *   framework default (90d) → adapter.defaultGracePeriodDays → per-org override
+ *
+ * Returned value is the effective grace period in days for THIS load.
+ */
+export function resolveEffectiveGracePeriodDays(adapter, spec) {
+    const perOrg = spec.deprecationOverrides?.gracePeriodDays;
+    if (typeof perOrg === 'number' && perOrg > 0)
+        return perOrg;
+    // Adapter-declared default lives on `capabilities` per OQ-4; we read it
+    // through a duck-typed lookup so adapters that don't declare it still
+    // type-check. (`EmbeddingCapabilities` is intentionally not extended
+    // here — the field is OPTIONAL and only known adapters set it.)
+    const adapterDeclared = adapter.capabilities
+        .defaultGracePeriodDays;
+    if (typeof adapterDeclared === 'number' && adapterDeclared > 0)
+        return adapterDeclared;
+    return EMBEDDING_DEFAULTS.gracePeriodDays;
+}
+/**
+ * Deprecation gate. Behaviour per OQ-4 re-walkthrough:
+ *   - past removedAt              → throw EmbeddingModelRemoved
+ *   - past deprecatedAt + strict  → throw EmbeddingModelDeprecated
+ *   - past deprecatedAt + default → emit warning event (continue load)
+ *   - inside grace window         → emit warning event (continue load)
+ *
+ * Catalog dedup (milestone counter at 89/60/30/7/1d before deprecatedAt) is
+ * the CALLER's responsibility — the loader emits one warning event per load;
+ * the orchestrator's Decision-catalog writer deduplicates by Decision key.
+ */
+function enforceDeprecationGate(adapter, spec, now, onDeprecationWarning) {
+    if (adapter.removedAt) {
+        const removedAt = new Date(adapter.removedAt);
+        if (now >= removedAt) {
+            throw new EmbeddingModelRemoved(adapter.name, adapter.removedAt, adapter.replacementAlias);
+        }
+    }
+    if (!adapter.deprecatedAt)
+        return;
+    const deprecatedAt = new Date(adapter.deprecatedAt);
+    const msPerDay = 24 * 60 * 60 * 1000;
+    const daysUntilDeprecated = Math.ceil((deprecatedAt.getTime() - now.getTime()) / msPerDay);
+    if (now >= deprecatedAt) {
+        if (spec.deprecationOverrides?.strictModeAtDeprecatedAt) {
+            throw new EmbeddingModelDeprecated(adapter.name, adapter.deprecatedAt, adapter.replacementAlias);
+        }
+        // Default mode: continue + emit warning (operators see the signal,
+        // pipeline keeps running until removedAt — per OQ-4 re-walkthrough).
+        onDeprecationWarning?.({
+            adapterName: adapter.name,
+            deprecatedAt: adapter.deprecatedAt,
+            removedAt: adapter.removedAt,
+            replacementAlias: adapter.replacementAlias,
+            daysUntilDeprecated,
+            effectiveGracePeriodDays: resolveEffectiveGracePeriodDays(adapter, spec),
+        });
+        // Surface the deprecating type as a side-effect-free reminder. We
+        // throw nothing here — load proceeds — but instantiate the error
+        // class so its shape stays in scope for diagnostic logging consumers.
+        void new EmbeddingModelDeprecating(adapter.name, adapter.deprecatedAt, adapter.replacementAlias);
+        return;
+    }
+    const effectiveGrace = resolveEffectiveGracePeriodDays(adapter, spec);
+    if (daysUntilDeprecated <= effectiveGrace) {
+        onDeprecationWarning?.({
+            adapterName: adapter.name,
+            deprecatedAt: adapter.deprecatedAt,
+            removedAt: adapter.removedAt,
+            replacementAlias: adapter.replacementAlias,
+            daysUntilDeprecated,
+            effectiveGracePeriodDays: effectiveGrace,
+        });
+    }
+}
+//# sourceMappingURL=pipeline-load.js.map

package/dist/embedding/registry.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Embedding adapter registry per RFC-0019 §6.1.
+ *
+ * Mirrors the HarnessRegistry pattern from orchestrator/src/harness/registry.ts.
+ * Pipeline-load calls getEmbeddingAdapter(name) to resolve the configured provider;
+ * fails fast with UnknownEmbeddingProvider when the name is not registered.
+ *
+ * The singleton EMBEDDING_ADAPTERS map is the registry. Adopters who need to
+ * register custom adapters should call registerEmbeddingAdapter() before
+ * pipeline-load resolves the embedding section.
+ */
+import type { EmbeddingAdapter } from './types.js';
+/**
+ * Resolve an embedding adapter by its canonical name.
+ *
+ * Throws UnknownEmbeddingProvider when the name is not in the registry.
+ * Pipeline-load MUST fail with this error so operator typos are caught
+ * at load time, not silently at the first embed() call site.
+ *
+ * @param name - Canonical adapter alias (e.g., 'openai-text-embedding-3-small').
+ */
+export declare function getEmbeddingAdapter(name: string): EmbeddingAdapter;
+/**
+ * Register a custom embedding adapter. Adopters call this before pipeline-load
+ * to extend the built-in registry with their own adapter implementations.
+ *
+ * Overwrites any existing adapter with the same name — intentional to support
+ * adopter forks that want to replace the default OpenAI adapter.
+ *
+ * @param adapter - Adapter instance implementing EmbeddingAdapter.
+ */
+export declare function registerEmbeddingAdapter(adapter: EmbeddingAdapter): void;
+/**
+ * Check whether a named adapter is registered (without throwing).
+ * Useful for conditional feature-flag checks at pipeline-load.
+ *
+ * @param name - Canonical adapter alias.
+ */
+export declare function hasEmbeddingAdapter(name: string): boolean;
+/**
+ * List all registered adapter names.
+ * Used in error messages and capability introspection.
+ */
+export declare function listEmbeddingAdapters(): string[];
+//# sourceMappingURL=registry.d.ts.map

package/dist/embedding/registry.js

@@ -0,0 +1,61 @@
+/**
+ * Embedding adapter registry per RFC-0019 §6.1.
+ *
+ * Mirrors the HarnessRegistry pattern from orchestrator/src/harness/registry.ts.
+ * Pipeline-load calls getEmbeddingAdapter(name) to resolve the configured provider;
+ * fails fast with UnknownEmbeddingProvider when the name is not registered.
+ *
+ * The singleton EMBEDDING_ADAPTERS map is the registry. Adopters who need to
+ * register custom adapters should call registerEmbeddingAdapter() before
+ * pipeline-load resolves the embedding section.
+ */
+import { UnknownEmbeddingProvider } from './errors.js';
+import { OpenAITextEmbedding3Small } from './adapters/openai-text-embedding-3-small.js';
+const EMBEDDING_ADAPTERS = new Map([
+    ['openai-text-embedding-3-small', new OpenAITextEmbedding3Small()],
+]);
+/**
+ * Resolve an embedding adapter by its canonical name.
+ *
+ * Throws UnknownEmbeddingProvider when the name is not in the registry.
+ * Pipeline-load MUST fail with this error so operator typos are caught
+ * at load time, not silently at the first embed() call site.
+ *
+ * @param name - Canonical adapter alias (e.g., 'openai-text-embedding-3-small').
+ */
+export function getEmbeddingAdapter(name) {
+    const adapter = EMBEDDING_ADAPTERS.get(name);
+    if (!adapter) {
+        throw new UnknownEmbeddingProvider(name, [...EMBEDDING_ADAPTERS.keys()]);
+    }
+    return adapter;
+}
+/**
+ * Register a custom embedding adapter. Adopters call this before pipeline-load
+ * to extend the built-in registry with their own adapter implementations.
+ *
+ * Overwrites any existing adapter with the same name — intentional to support
+ * adopter forks that want to replace the default OpenAI adapter.
+ *
+ * @param adapter - Adapter instance implementing EmbeddingAdapter.
+ */
+export function registerEmbeddingAdapter(adapter) {
+    EMBEDDING_ADAPTERS.set(adapter.name, adapter);
+}
+/**
+ * Check whether a named adapter is registered (without throwing).
+ * Useful for conditional feature-flag checks at pipeline-load.
+ *
+ * @param name - Canonical adapter alias.
+ */
+export function hasEmbeddingAdapter(name) {
+    return EMBEDDING_ADAPTERS.has(name);
+}
+/**
+ * List all registered adapter names.
+ * Used in error messages and capability introspection.
+ */
+export function listEmbeddingAdapters() {
+    return [...EMBEDDING_ADAPTERS.keys()];
+}
+//# sourceMappingURL=registry.js.map

package/dist/embedding/stale-vector.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Stale-vector policy resolution per RFC-0019 §9.3 + OQ-2 re-walkthrough.
+ *
+ * When a read encounters a vector whose (embeddingProvider, embeddingModelVersion)
+ * does not match the currently configured adapter, the read path follows one
+ * of three policies:
+ *
+ *  - `lazy`     — re-embed the source text with the current adapter and return
+ *                 the new vector. The framework default; favours operator
+ *                 convenience over strict provenance.
+ *  - `fail-loud` — refuse the comparison and throw `StaleVectorEncountered`.
+ *                  Used by consumers like RFC-0009 Eτ_tessellation_drift where
+ *                  silently overwriting a historical vector destroys time-series
+ *                  signal.
+ *  - `inherit`  — defer to the org-level default (and ultimately the framework
+ *                 default of `lazy`). Per-consumer call sites typically pass
+ *                 `inherit` when they have no opinion.
+ *
+ * The OQ-2 re-walkthrough resolution added an explicit per-consumer override
+ * API parameter on top of the org default. RFC-0009 drift pins `fail-loud` at
+ * its call sites; common-case consumers (PPA similarity, DoR dedup, classifier
+ * embeddings) leave the default. This module implements the three-layer
+ * inheritance chain (per-call → org default → framework default).
+ *
+ * Cross-cutting framing per RFC-0035 G0: a stale-vector encounter ALWAYS
+ * produces a `Decision: stale-vector-encountered` event, regardless of policy.
+ * Under `lazy` the event is informational (low severity). Under `fail-loud`
+ * the event is HIGH severity and surfaced in the operator batch review.
+ *
+ * @module embedding/stale-vector
+ */
+import { EmbeddingError } from './errors.js';
+/**
+ * Resolved policy that the read path actually applies.
+ * Distinct from `StaleVectorPolicyInput` because `inherit` is never the
+ * effective policy — it always resolves to either `lazy` or `fail-loud`.
+ */
+export type StaleVectorPolicy = 'lazy' | 'fail-loud';
+/**
+ * Policy value callers may pass at the API site.
+ * `inherit` means "use the org default (which falls back to framework default)".
+ */
+export type StaleVectorPolicyInput = StaleVectorPolicy | 'inherit';
+/**
+ * Framework-level default. Per OQ-2 re-walkthrough: `lazy` because the common
+ * case (issue dedup, clarification matching) is operator-interactive daily,
+ * while strict-provenance use cases (drift trajectory) are once-a-week
+ * analyses. Asymmetric impact warrants asymmetric default.
+ */
+export declare const FRAMEWORK_DEFAULT_STALE_VECTOR_POLICY: StaleVectorPolicy;
+/**
+ * Resolve the effective stale-vector policy from the three-layer chain.
+ *
+ * Precedence (highest to lowest):
+ *   1. `perCallOverride` — the value passed at the embed() / read() call site
+ *      (e.g., RFC-0009 drift pins `fail-loud`). `inherit` defers to layer 2.
+ *   2. `orgDefault` — per-org configuration (`embedding-config.yaml`
+ *      `staleVectorPolicy.default`). Undefined defers to layer 3.
+ *   3. Framework default — `FRAMEWORK_DEFAULT_STALE_VECTOR_POLICY` (= `lazy`).
+ *
+ * @param perCallOverride - Optional per-call override. `inherit` defers up.
+ * @param orgDefault - Optional org-level default. Undefined defers to framework.
+ * @returns The effective policy: `lazy` or `fail-loud`.
+ */
+export declare function resolveStaleVectorPolicy(perCallOverride: StaleVectorPolicyInput | undefined, orgDefault: StaleVectorPolicy | undefined): StaleVectorPolicy;
+/**
+ * Severity used for the `Decision: stale-vector-encountered` catalog event.
+ * Mirrors the operator-impact surface — `lazy` runs as a silent informational
+ * decision; `fail-loud` is escalated for batch review.
+ */
+export type StaleVectorDecisionSeverity = 'info' | 'high';
+/**
+ * Map a resolved policy to the catalog Decision severity per OQ-2 re-walkthrough.
+ */
+export declare function severityForPolicy(policy: StaleVectorPolicy): StaleVectorDecisionSeverity;
+/**
+ * Inputs describing a single stale-vector encounter.
+ */
+export interface StaleVectorContext {
+    /** Provider on the stored entry (e.g., 'openai-text-embedding-ada-002'). */
+    storedProvider: string;
+    /** Model version on the stored entry. */
+    storedModelVersion: string;
+    /** Adapter the caller is currently configured to use. */
+    currentProvider: string;
+    /** Model version on the current adapter. */
+    currentModelVersion: string;
+    /** SHA-256 of the source text — the lookup key that surfaced the stale entry. */
+    textHash: string;
+    /**
+     * Optional consumer label so the catalog event can be attributed back to
+     * the calling subsystem (e.g., 'rfc-0009-tessellation-drift').
+     */
+    consumerLabel?: string;
+}
+/**
+ * Thrown by the read path when the resolved policy is `fail-loud`.
+ * Carries the full context so callers can build a useful operator message.
+ */
+export declare class StaleVectorEncountered extends EmbeddingError {
+    readonly context: StaleVectorContext;
+    constructor(context: StaleVectorContext);
+}
+/**
+ * Whether a stored entry's provenance matches the current adapter.
+ * Returns `true` when both provider and modelVersion match — i.e., the entry
+ * is NOT stale and no policy enforcement is needed.
+ */
+export declare function isCurrentVector(storedProvider: string, storedModelVersion: string, currentProvider: string, currentModelVersion: string): boolean;
+//# sourceMappingURL=stale-vector.d.ts.map

package/dist/embedding/stale-vector.js

@@ -0,0 +1,92 @@
+/**
+ * Stale-vector policy resolution per RFC-0019 §9.3 + OQ-2 re-walkthrough.
+ *
+ * When a read encounters a vector whose (embeddingProvider, embeddingModelVersion)
+ * does not match the currently configured adapter, the read path follows one
+ * of three policies:
+ *
+ *  - `lazy`     — re-embed the source text with the current adapter and return
+ *                 the new vector. The framework default; favours operator
+ *                 convenience over strict provenance.
+ *  - `fail-loud` — refuse the comparison and throw `StaleVectorEncountered`.
+ *                  Used by consumers like RFC-0009 Eτ_tessellation_drift where
+ *                  silently overwriting a historical vector destroys time-series
+ *                  signal.
+ *  - `inherit`  — defer to the org-level default (and ultimately the framework
+ *                 default of `lazy`). Per-consumer call sites typically pass
+ *                 `inherit` when they have no opinion.
+ *
+ * The OQ-2 re-walkthrough resolution added an explicit per-consumer override
+ * API parameter on top of the org default. RFC-0009 drift pins `fail-loud` at
+ * its call sites; common-case consumers (PPA similarity, DoR dedup, classifier
+ * embeddings) leave the default. This module implements the three-layer
+ * inheritance chain (per-call → org default → framework default).
+ *
+ * Cross-cutting framing per RFC-0035 G0: a stale-vector encounter ALWAYS
+ * produces a `Decision: stale-vector-encountered` event, regardless of policy.
+ * Under `lazy` the event is informational (low severity). Under `fail-loud`
+ * the event is HIGH severity and surfaced in the operator batch review.
+ *
+ * @module embedding/stale-vector
+ */
+import { EmbeddingError } from './errors.js';
+/**
+ * Framework-level default. Per OQ-2 re-walkthrough: `lazy` because the common
+ * case (issue dedup, clarification matching) is operator-interactive daily,
+ * while strict-provenance use cases (drift trajectory) are once-a-week
+ * analyses. Asymmetric impact warrants asymmetric default.
+ */
+export const FRAMEWORK_DEFAULT_STALE_VECTOR_POLICY = 'lazy';
+/**
+ * Resolve the effective stale-vector policy from the three-layer chain.
+ *
+ * Precedence (highest to lowest):
+ *   1. `perCallOverride` — the value passed at the embed() / read() call site
+ *      (e.g., RFC-0009 drift pins `fail-loud`). `inherit` defers to layer 2.
+ *   2. `orgDefault` — per-org configuration (`embedding-config.yaml`
+ *      `staleVectorPolicy.default`). Undefined defers to layer 3.
+ *   3. Framework default — `FRAMEWORK_DEFAULT_STALE_VECTOR_POLICY` (= `lazy`).
+ *
+ * @param perCallOverride - Optional per-call override. `inherit` defers up.
+ * @param orgDefault - Optional org-level default. Undefined defers to framework.
+ * @returns The effective policy: `lazy` or `fail-loud`.
+ */
+export function resolveStaleVectorPolicy(perCallOverride, orgDefault) {
+    if (perCallOverride && perCallOverride !== 'inherit') {
+        return perCallOverride;
+    }
+    if (orgDefault) {
+        return orgDefault;
+    }
+    return FRAMEWORK_DEFAULT_STALE_VECTOR_POLICY;
+}
+/**
+ * Map a resolved policy to the catalog Decision severity per OQ-2 re-walkthrough.
+ */
+export function severityForPolicy(policy) {
+    return policy === 'fail-loud' ? 'high' : 'info';
+}
+/**
+ * Thrown by the read path when the resolved policy is `fail-loud`.
+ * Carries the full context so callers can build a useful operator message.
+ */
+export class StaleVectorEncountered extends EmbeddingError {
+    context;
+    constructor(context) {
+        super(`Stale embedding vector encountered: stored ${context.storedProvider}@${context.storedModelVersion}, ` +
+            `current ${context.currentProvider}@${context.currentModelVersion}. ` +
+            `Policy 'fail-loud' refuses the comparison. ` +
+            `Migrate via: cli-embedding-bump --to ${context.currentProvider}`);
+        this.context = context;
+        this.name = 'StaleVectorEncountered';
+    }
+}
+/**
+ * Whether a stored entry's provenance matches the current adapter.
+ * Returns `true` when both provider and modelVersion match — i.e., the entry
+ * is NOT stale and no policy enforcement is needed.
+ */
+export function isCurrentVector(storedProvider, storedModelVersion, currentProvider, currentModelVersion) {
+    return storedProvider === currentProvider && storedModelVersion === currentModelVersion;
+}
+//# sourceMappingURL=stale-vector.js.map

package/dist/embedding/storage/index.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Embedding storage backend factory per RFC-0019 §8.3 + Phase 2.
+ *
+ * Factory is keyed on `Pipeline.spec.embedding.storageBackend` (the
+ * 'storageBackend' string from pipeline config). Currently supports:
+ *   - 'jsonl' (default): JSONL append-only backend at <artifactsDir>/_embeddings/
+ *
+ * Future backends ('sqlite', 'pgvector', 'qdrant', etc.) implement the
+ * EmbeddingStorageBackend interface and register themselves here.
+ *
+ * Usage:
+ *   const backend = createEmbeddingStorageBackend('jsonl', '/path/to/artifacts');
+ */
+export type { EmbeddingStorageBackend, VectorStoreEntry, VectorStoreFilter } from './types.js';
+export { JsonlEmbeddingStorageBackend, SCALE_ESCALATION_MAX_ENTRIES, SCALE_ESCALATION_P95_READ_MS, } from './jsonl-backend.js';
+export type { ScaleEscalationSignal } from './jsonl-backend.js';
+import type { EmbeddingStorageBackend } from './types.js';
+import type { ScaleEscalationSignal } from './jsonl-backend.js';
+/**
+ * Known storage backend names.
+ * Extend this union when adding new backends.
+ */
+export type StorageBackendName = 'jsonl' | (string & Record<never, never>);
+/**
+ * Options passed to the backend factory.
+ */
+export interface StorageBackendOptions {
+    /**
+     * Optional scale-escalation callback. Called when the backend detects
+     * that it is approaching operational limits (>100K entries OR p95 read >250ms).
+     * Wire to your telemetry layer; defaults to console.warn inside the backend.
+     */
+    onScaleEscalation?: (signal: ScaleEscalationSignal) => void;
+}
+/**
+ * Create an EmbeddingStorageBackend from a backend name + artifacts directory.
+ *
+ * @param backendName - Backend identifier from Pipeline.spec.embedding.storageBackend.
+ *   Defaults to 'jsonl' when omitted or undefined.
+ * @param artifactsDir - Path to the artifacts directory. The backend creates its
+ *   subdirectory (e.g., `_embeddings/`) under this path.
+ * @param options - Optional factory options.
+ *
+ * @throws {Error} When `backendName` is not a known backend.
+ *
+ * @example
+ *   const backend = createEmbeddingStorageBackend('jsonl', process.env.ARTIFACTS_DIR ?? '.ai-sdlc');
+ *   await backend.write({ ... });
+ */
+export declare function createEmbeddingStorageBackend(backendName: StorageBackendName | undefined, artifactsDir: string, options?: StorageBackendOptions): EmbeddingStorageBackend;
+//# sourceMappingURL=index.d.ts.map

package/dist/embedding/storage/index.js

@@ -0,0 +1,43 @@
+/**
+ * Embedding storage backend factory per RFC-0019 §8.3 + Phase 2.
+ *
+ * Factory is keyed on `Pipeline.spec.embedding.storageBackend` (the
+ * 'storageBackend' string from pipeline config). Currently supports:
+ *   - 'jsonl' (default): JSONL append-only backend at <artifactsDir>/_embeddings/
+ *
+ * Future backends ('sqlite', 'pgvector', 'qdrant', etc.) implement the
+ * EmbeddingStorageBackend interface and register themselves here.
+ *
+ * Usage:
+ *   const backend = createEmbeddingStorageBackend('jsonl', '/path/to/artifacts');
+ */
+export { JsonlEmbeddingStorageBackend, SCALE_ESCALATION_MAX_ENTRIES, SCALE_ESCALATION_P95_READ_MS, } from './jsonl-backend.js';
+import { JsonlEmbeddingStorageBackend } from './jsonl-backend.js';
+/**
+ * Create an EmbeddingStorageBackend from a backend name + artifacts directory.
+ *
+ * @param backendName - Backend identifier from Pipeline.spec.embedding.storageBackend.
+ *   Defaults to 'jsonl' when omitted or undefined.
+ * @param artifactsDir - Path to the artifacts directory. The backend creates its
+ *   subdirectory (e.g., `_embeddings/`) under this path.
+ * @param options - Optional factory options.
+ *
+ * @throws {Error} When `backendName` is not a known backend.
+ *
+ * @example
+ *   const backend = createEmbeddingStorageBackend('jsonl', process.env.ARTIFACTS_DIR ?? '.ai-sdlc');
+ *   await backend.write({ ... });
+ */
+export function createEmbeddingStorageBackend(backendName = 'jsonl', artifactsDir, options) {
+    switch (backendName) {
+        case 'jsonl':
+            return new JsonlEmbeddingStorageBackend(artifactsDir, {
+                onScaleEscalation: options?.onScaleEscalation,
+            });
+        default:
+            throw new Error(`Unknown embedding storage backend '${backendName}'. ` +
+                `Known backends: ['jsonl']. ` +
+                `To add a custom backend, implement EmbeddingStorageBackend and add a case here.`);
+    }
+}
+//# sourceMappingURL=index.js.map