@ai-sdlc/orchestrator 0.10.0 → 0.14.0

package/dist/embedding/deprecation.js

@@ -0,0 +1,229 @@
+/**
+ * Deprecation lifecycle per RFC-0019 §9.1 + OQ-4 re-walkthrough.
+ *
+ * Three-layer grace-period precedence (highest → lowest):
+ *   1. per-org `gracePeriodDays` from `.ai-sdlc/embedding-config.yaml`
+ *   2. adapter-declared `defaultGracePeriodDays` (capability matrix)
+ *   3. framework default — 90 days
+ *
+ * Catalog dedup via per-Decision-key counter prevents Decision flood under
+ * orchestrator-driven loads: emit `Decision: embedding-provider-deprecated`
+ * at MILESTONES (89/60/30/7/1 days before deprecatedAt), NOT per-load. The
+ * dedup key is `embedding-provider-deprecated:<adapter-name>:<deprecatedAt>`.
+ *
+ * Lifecycle phases:
+ *   - Pre-warning   : today < (deprecatedAt - gracePeriod) → silent
+ *   - Warning       : today ∈ [deprecatedAt - gracePeriod, deprecatedAt) → milestone events
+ *   - Deprecated    : today ∈ [deprecatedAt, removedAt) → continued warnings; HIGH in strict mode
+ *   - Removed       : today ≥ removedAt → emit `Decision: embedding-provider-removed`
+ *                     + auto-action: emit cli-embedding-bump migration task.
+ *                     Pipeline NEVER halts — downstream consumers degrade.
+ *
+ * @module embedding/deprecation
+ */
+/**
+ * Framework default grace-period length per OQ-4 re-walkthrough.
+ * Conservative within OpenAI's typical 12-15 month deprecation window.
+ */
+export const FRAMEWORK_DEFAULT_GRACE_PERIOD_DAYS = 90;
+/**
+ * Days-before-deprecatedAt at which a catalog Decision is emitted.
+ * Dedup counter ensures one event per milestone per (adapter, deprecatedAt) tuple.
+ *
+ * Sorted DESCENDING — when computing "next-due milestone" we walk from
+ * largest to smallest and pick the first one we have crossed.
+ */
+export const DEPRECATION_MILESTONE_DAYS = [89, 60, 30, 7, 1];
+/**
+ * Resolve the effective grace period using the three-layer precedence chain
+ * per OQ-4 re-walkthrough.
+ */
+export function resolveGracePeriodDays(orgOverride, adapterDefault) {
+    if (typeof orgOverride === 'number' && Number.isFinite(orgOverride) && orgOverride > 0) {
+        return orgOverride;
+    }
+    if (typeof adapterDefault === 'number' && Number.isFinite(adapterDefault) && adapterDefault > 0) {
+        return adapterDefault;
+    }
+    return FRAMEWORK_DEFAULT_GRACE_PERIOD_DAYS;
+}
+/** Compute calendar-day difference (positive = future, negative = past). */
+function daysBetween(from, to) {
+    const MS_PER_DAY = 1000 * 60 * 60 * 24;
+    // Normalize to UTC midnight so DST transitions don't bias the count.
+    const fromUtc = Date.UTC(from.getUTCFullYear(), from.getUTCMonth(), from.getUTCDate());
+    const toUtc = Date.UTC(to.getUTCFullYear(), to.getUTCMonth(), to.getUTCDate());
+    return Math.round((toUtc - fromUtc) / MS_PER_DAY);
+}
+/**
+ * Find the most-recently-crossed milestone at the current moment — i.e., the
+ * SMALLEST milestone the caller is at-or-under. Returns `null` when no
+ * milestone is due (today is BEFORE the largest milestone OR adapter has no
+ * deprecatedAt).
+ *
+ * "Crossed" = `daysToDeprecatedAt <= milestone`. We want the smallest such
+ * milestone so each emission represents a NEW threshold crossed:
+ *
+ *   90 days out → no milestone due
+ *   89 days out → milestone 89 (largest threshold first crossed)
+ *   75 days out → milestone 89 (still inside 89 window, 60 not yet crossed)
+ *   60 days out → milestone 60 (newly crossed)
+ *   50 days out → milestone 60 (still inside 60, 30 not yet crossed)
+ *   30 days out → milestone 30
+ *   ...
+ *
+ * The dedup counter then collapses repeated emissions at the same milestone
+ * to exactly one event per (adapter, deprecatedAt, milestone) tuple.
+ *
+ * @param daysToDeprecatedAt - Result from `daysBetween(today, deprecatedAt)`.
+ *   Positive when deprecatedAt is in the future, negative when past.
+ */
+export function nextDueMilestone(daysToDeprecatedAt) {
+    // After deprecatedAt: no milestone is "due" (we emit the deprecated phase
+    // event instead).
+    if (daysToDeprecatedAt < 0)
+        return null;
+    // Sorted ASCENDING for this lookup: pick the SMALLEST milestone we are
+    // at-or-under so each crossing surfaces as a distinct emission.
+    const ascending = [...DEPRECATION_MILESTONE_DAYS].sort((a, b) => a - b);
+    for (const milestone of ascending) {
+        if (daysToDeprecatedAt <= milestone)
+            return milestone;
+    }
+    return null;
+}
+/**
+ * Build the catalog dedup key for a deprecation event at a given milestone.
+ * Same key across pipeline loads → caller refuses to emit a second time.
+ */
+export function buildDedupKey(decisionType, adapterName, deprecatedAt, milestoneDaysBefore) {
+    const base = `${decisionType}:${adapterName}:${deprecatedAt ?? 'undeclared'}`;
+    return milestoneDaysBefore === null ? base : `${base}:m${milestoneDaysBefore}`;
+}
+/**
+ * Evaluate the deprecation lifecycle for one adapter.
+ *
+ * Returns the phase, resolved grace period, and any catalog Decision events
+ * the caller should emit. Pipeline-load NEVER halts on the result; downstream
+ * consumers degrade gracefully per the RFC-0035 G0 non-blocking contract.
+ *
+ * Dedup contract: the returned `decisionEvents` always carry the dedup key.
+ * The caller MUST consult its dedup store before appending — re-emitting the
+ * same `(adapter, deprecatedAt, milestone)` triple is a bug.
+ */
+export function evaluateDeprecationLifecycle(input) {
+    const today = input.today ?? new Date();
+    const effectiveGracePeriodDays = resolveGracePeriodDays(input.orgGracePeriodDays, input.adapterDefaultGracePeriodDays);
+    // Inactive — no lifecycle declared.
+    if (!input.deprecatedAt && !input.removedAt) {
+        return {
+            phase: 'inactive',
+            effectiveGracePeriodDays,
+            daysToDeprecatedAt: null,
+            daysToRemovedAt: null,
+            decisionEvents: [],
+        };
+    }
+    const daysToDeprecatedAt = input.deprecatedAt
+        ? daysBetween(today, new Date(input.deprecatedAt))
+        : null;
+    const daysToRemovedAt = input.removedAt ? daysBetween(today, new Date(input.removedAt)) : null;
+    // Removed — strongest signal. Always emit migration task.
+    if (daysToRemovedAt !== null && daysToRemovedAt <= 0) {
+        const dedupKey = buildDedupKey('embedding-provider-removed', input.adapterName, input.deprecatedAt, null);
+        return {
+            phase: 'removed',
+            effectiveGracePeriodDays,
+            daysToDeprecatedAt,
+            daysToRemovedAt,
+            decisionEvents: [
+                {
+                    decisionType: 'embedding-provider-removed',
+                    dedupKey,
+                    severity: 'high',
+                    summary: `Embedding adapter '${input.adapterName}' was removed on ${input.removedAt}. ` +
+                        `Downstream consumers degrade gracefully (no pipeline halt). ` +
+                        (input.replacementAlias
+                            ? `Migrate via: cli-embedding-bump --to ${input.replacementAlias}`
+                            : 'No replacement alias declared.'),
+                    milestoneDaysBefore: null,
+                    autoAction: 'emit-migration-task',
+                },
+            ],
+        };
+    }
+    // Deprecated — past deprecatedAt but before removedAt.
+    if (daysToDeprecatedAt !== null && daysToDeprecatedAt <= 0) {
+        const severity = input.strictModeAtDeprecatedAt ? 'high' : 'info';
+        const dedupKey = buildDedupKey('embedding-provider-deprecated', input.adapterName, input.deprecatedAt, 
+        // Post-deprecatedAt: dedup on "phase-deprecated" rather than a milestone.
+        // Use a sentinel value (0) so future loads with the same key stay deduped.
+        0);
+        return {
+            phase: 'deprecated',
+            effectiveGracePeriodDays,
+            daysToDeprecatedAt,
+            daysToRemovedAt,
+            decisionEvents: [
+                {
+                    decisionType: 'embedding-provider-deprecated',
+                    dedupKey,
+                    severity,
+                    summary: `Embedding adapter '${input.adapterName}' was deprecated on ${input.deprecatedAt}. ` +
+                        (input.replacementAlias
+                            ? `Run: cli-embedding-bump --to ${input.replacementAlias}`
+                            : 'No replacement alias declared.'),
+                    milestoneDaysBefore: 0,
+                    autoAction: null,
+                },
+            ],
+        };
+    }
+    // Warning period — today ∈ [deprecatedAt - gracePeriod, deprecatedAt).
+    if (daysToDeprecatedAt !== null &&
+        daysToDeprecatedAt > 0 &&
+        daysToDeprecatedAt <= effectiveGracePeriodDays) {
+        const milestone = nextDueMilestone(daysToDeprecatedAt);
+        if (milestone === null) {
+            // We are inside the warning window but BEFORE the largest milestone (89d).
+            // No event to emit yet.
+            return {
+                phase: 'warning',
+                effectiveGracePeriodDays,
+                daysToDeprecatedAt,
+                daysToRemovedAt,
+                decisionEvents: [],
+            };
+        }
+        const dedupKey = buildDedupKey('embedding-provider-deprecated', input.adapterName, input.deprecatedAt, milestone);
+        return {
+            phase: 'warning',
+            effectiveGracePeriodDays,
+            daysToDeprecatedAt,
+            daysToRemovedAt,
+            decisionEvents: [
+                {
+                    decisionType: 'embedding-provider-deprecated',
+                    dedupKey,
+                    severity: 'info',
+                    summary: `Embedding adapter '${input.adapterName}' will be deprecated on ${input.deprecatedAt} ` +
+                        `(${daysToDeprecatedAt} days, milestone ${milestone}d). ` +
+                        (input.replacementAlias
+                            ? `Migrate via: cli-embedding-bump --to ${input.replacementAlias}`
+                            : 'No replacement alias declared.'),
+                    milestoneDaysBefore: milestone,
+                    autoAction: null,
+                },
+            ],
+        };
+    }
+    // Pre-warning — today is more than `gracePeriodDays` before deprecatedAt.
+    return {
+        phase: 'pre-warning',
+        effectiveGracePeriodDays,
+        daysToDeprecatedAt,
+        daysToRemovedAt,
+        decisionEvents: [],
+    };
+}
+//# sourceMappingURL=deprecation.js.map

package/dist/embedding/errors.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Error classes for the embedding adapter framework per RFC-0019 §11.
+ *
+ * Error hierarchy:
+ *   EmbeddingError (base)
+ *   ├── UnknownEmbeddingProvider   — registry miss (fail-fast at pipeline-load)
+ *   ├── EmbeddingProviderUnavailable — isAvailable() returned false
+ *   ├── EmbeddingProviderError     — upstream API error during embed()
+ *   ├── EmbeddingDimensionMismatch — vector length != adapter.dimensions
+ *   ├── EmbeddingModelDeprecating  — deprecation warning (not fatal)
+ *   ├── EmbeddingModelDeprecated   — deprecated error (fatal in strict mode)
+ *   └── EmbeddingModelRemoved      — past removedAt (always fatal)
+ */
+/**
+ * Base class for all embedding framework errors.
+ */
+export declare class EmbeddingError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown by getEmbeddingAdapter() when the requested adapter name
+ * is not present in the registry. Pipeline-load fails with this error
+ * so operator typos are caught at load time, not at first embed() call.
+ */
+export declare class UnknownEmbeddingProvider extends EmbeddingError {
+    readonly requestedName: string;
+    readonly availableNames: string[];
+    constructor(requestedName: string, availableNames: string[]);
+}
+/**
+ * Thrown by the orchestrator when adapter.isAvailable() returns { available: false }.
+ * Pipeline-load fails with this error naming the reason and detail from the probe.
+ */
+export declare class EmbeddingProviderUnavailable extends EmbeddingError {
+    readonly adapterName: string;
+    readonly reason: string;
+    readonly detail?: string | undefined;
+    constructor(adapterName: string, reason: string, detail?: string | undefined);
+}
+/**
+ * Thrown by adapter.embed() when the upstream API returns an error.
+ * Wraps the provider-specific error detail for operator-facing diagnostics.
+ */
+export declare class EmbeddingProviderError extends EmbeddingError {
+    readonly adapterName: string;
+    readonly detail: string;
+    constructor(adapterName: string, detail: string, cause?: unknown);
+}
+/**
+ * Thrown when the vector returned by embed() has a different length than
+ * adapter.dimensions. Indicates an adapter implementation bug or provider
+ * configuration drift.
+ */
+export declare class EmbeddingDimensionMismatch extends EmbeddingError {
+    readonly adapterName: string;
+    readonly expectedDimensions: number;
+    readonly actualDimensions: number;
+    constructor(adapterName: string, expectedDimensions: number, actualDimensions: number);
+}
+/**
+ * Emitted as a warning (not thrown) when today is within 90 days of adapter.deprecatedAt.
+ * Adapter still functions normally during the warning period.
+ */
+export declare class EmbeddingModelDeprecating extends EmbeddingError {
+    readonly adapterName: string;
+    readonly deprecatedAt: string;
+    readonly replacementAlias?: string | undefined;
+    constructor(adapterName: string, deprecatedAt: string, replacementAlias?: string | undefined);
+}
+/**
+ * Thrown when today >= adapter.deprecatedAt (in strict mode) or emitted as a
+ * warning (in default mode). Adapter still functions in non-strict mode.
+ */
+export declare class EmbeddingModelDeprecated extends EmbeddingError {
+    readonly adapterName: string;
+    readonly deprecatedAt: string;
+    readonly replacementAlias?: string | undefined;
+    constructor(adapterName: string, deprecatedAt: string, replacementAlias?: string | undefined);
+}
+/**
+ * Always fatal. Thrown when today >= adapter.removedAt.
+ * Pipeline-load fails and the operator MUST run cli-embedding-bump to migrate.
+ */
+export declare class EmbeddingModelRemoved extends EmbeddingError {
+    readonly adapterName: string;
+    readonly removedAt: string;
+    readonly replacementAlias?: string | undefined;
+    constructor(adapterName: string, removedAt: string, replacementAlias?: string | undefined);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/embedding/errors.js

@@ -0,0 +1,150 @@
+/**
+ * Error classes for the embedding adapter framework per RFC-0019 §11.
+ *
+ * Error hierarchy:
+ *   EmbeddingError (base)
+ *   ├── UnknownEmbeddingProvider   — registry miss (fail-fast at pipeline-load)
+ *   ├── EmbeddingProviderUnavailable — isAvailable() returned false
+ *   ├── EmbeddingProviderError     — upstream API error during embed()
+ *   ├── EmbeddingDimensionMismatch — vector length != adapter.dimensions
+ *   ├── EmbeddingModelDeprecating  — deprecation warning (not fatal)
+ *   ├── EmbeddingModelDeprecated   — deprecated error (fatal in strict mode)
+ *   └── EmbeddingModelRemoved      — past removedAt (always fatal)
+ */
+/**
+ * Base class for all embedding framework errors.
+ */
+export class EmbeddingError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'EmbeddingError';
+    }
+}
+/**
+ * Thrown by getEmbeddingAdapter() when the requested adapter name
+ * is not present in the registry. Pipeline-load fails with this error
+ * so operator typos are caught at load time, not at first embed() call.
+ */
+export class UnknownEmbeddingProvider extends EmbeddingError {
+    requestedName;
+    availableNames;
+    constructor(requestedName, availableNames) {
+        super(`Unknown embedding provider '${requestedName}'. ` +
+            `Available providers: [${availableNames.join(', ')}]. ` +
+            `Register the adapter in orchestrator/src/embedding/registry.ts or check your spelling.`);
+        this.requestedName = requestedName;
+        this.availableNames = availableNames;
+        this.name = 'UnknownEmbeddingProvider';
+    }
+}
+/**
+ * Thrown by the orchestrator when adapter.isAvailable() returns { available: false }.
+ * Pipeline-load fails with this error naming the reason and detail from the probe.
+ */
+export class EmbeddingProviderUnavailable extends EmbeddingError {
+    adapterName;
+    reason;
+    detail;
+    constructor(adapterName, reason, detail) {
+        super(`Embedding provider '${adapterName}' is unavailable (reason: ${reason}).` +
+            (detail ? ` ${detail}` : ''));
+        this.adapterName = adapterName;
+        this.reason = reason;
+        this.detail = detail;
+        this.name = 'EmbeddingProviderUnavailable';
+    }
+}
+/**
+ * Thrown by adapter.embed() when the upstream API returns an error.
+ * Wraps the provider-specific error detail for operator-facing diagnostics.
+ */
+export class EmbeddingProviderError extends EmbeddingError {
+    adapterName;
+    detail;
+    constructor(adapterName, detail, cause) {
+        super(`Embedding provider '${adapterName}' returned an error: ${detail}`);
+        this.adapterName = adapterName;
+        this.detail = detail;
+        this.name = 'EmbeddingProviderError';
+        if (cause) {
+            this.cause = cause;
+        }
+    }
+}
+/**
+ * Thrown when the vector returned by embed() has a different length than
+ * adapter.dimensions. Indicates an adapter implementation bug or provider
+ * configuration drift.
+ */
+export class EmbeddingDimensionMismatch extends EmbeddingError {
+    adapterName;
+    expectedDimensions;
+    actualDimensions;
+    constructor(adapterName, expectedDimensions, actualDimensions) {
+        super(`Dimension mismatch for adapter '${adapterName}': ` +
+            `expected ${expectedDimensions} dimensions but got ${actualDimensions}. ` +
+            `This indicates a provider configuration change or adapter implementation bug.`);
+        this.adapterName = adapterName;
+        this.expectedDimensions = expectedDimensions;
+        this.actualDimensions = actualDimensions;
+        this.name = 'EmbeddingDimensionMismatch';
+    }
+}
+/**
+ * Emitted as a warning (not thrown) when today is within 90 days of adapter.deprecatedAt.
+ * Adapter still functions normally during the warning period.
+ */
+export class EmbeddingModelDeprecating extends EmbeddingError {
+    adapterName;
+    deprecatedAt;
+    replacementAlias;
+    constructor(adapterName, deprecatedAt, replacementAlias) {
+        super(`Embedding adapter '${adapterName}' will be deprecated on ${deprecatedAt}. ` +
+            (replacementAlias
+                ? `Migrate to '${replacementAlias}' using: cli-embedding-bump --to ${replacementAlias}`
+                : 'No replacement alias declared — check the adapter documentation.'));
+        this.adapterName = adapterName;
+        this.deprecatedAt = deprecatedAt;
+        this.replacementAlias = replacementAlias;
+        this.name = 'EmbeddingModelDeprecating';
+    }
+}
+/**
+ * Thrown when today >= adapter.deprecatedAt (in strict mode) or emitted as a
+ * warning (in default mode). Adapter still functions in non-strict mode.
+ */
+export class EmbeddingModelDeprecated extends EmbeddingError {
+    adapterName;
+    deprecatedAt;
+    replacementAlias;
+    constructor(adapterName, deprecatedAt, replacementAlias) {
+        super(`Embedding adapter '${adapterName}' was deprecated on ${deprecatedAt}. ` +
+            (replacementAlias
+                ? `Run: cli-embedding-bump --to ${replacementAlias}`
+                : 'No replacement alias declared — check the adapter documentation.'));
+        this.adapterName = adapterName;
+        this.deprecatedAt = deprecatedAt;
+        this.replacementAlias = replacementAlias;
+        this.name = 'EmbeddingModelDeprecated';
+    }
+}
+/**
+ * Always fatal. Thrown when today >= adapter.removedAt.
+ * Pipeline-load fails and the operator MUST run cli-embedding-bump to migrate.
+ */
+export class EmbeddingModelRemoved extends EmbeddingError {
+    adapterName;
+    removedAt;
+    replacementAlias;
+    constructor(adapterName, removedAt, replacementAlias) {
+        super(`Embedding adapter '${adapterName}' was removed on ${removedAt} and can no longer be used. ` +
+            (replacementAlias
+                ? `Migrate by running: cli-embedding-bump --to ${replacementAlias}`
+                : 'No replacement alias declared — check the adapter documentation.'));
+        this.adapterName = adapterName;
+        this.removedAt = removedAt;
+        this.replacementAlias = replacementAlias;
+        this.name = 'EmbeddingModelRemoved';
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/embedding/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Embedding adapter framework per RFC-0019.
+ * Phase 1: interface + registry + OpenAI default adapter + errors.
+ * Phase 2: vector storage backend + JSONL default + backend factory + GC.
+ * Phase 3: stale-vector policy, cross-provider compatibility, deprecation
+ *          lifecycle (AISDLC-339). Migration tooling itself lives in
+ *          `pipeline-cli/src/cli/embedding-bump.ts`.
+ * Phase 4 (AISDLC-340): pipeline-load wiring + first-consumer (Eτ drift) spec stub.
+ *
+ * Phase 5 (soak) ships in AISDLC-341.
+ */
+export type { EmbeddingAdapter, EmbeddingAvailability, EmbeddingCapabilities, EmbeddingRequires, EmbeddingBillingModel, EmbeddingCostRecord, } from './types.js';
+export { EmbeddingError, UnknownEmbeddingProvider, EmbeddingProviderUnavailable, EmbeddingProviderError, EmbeddingDimensionMismatch, EmbeddingModelDeprecating, EmbeddingModelDeprecated, EmbeddingModelRemoved, } from './errors.js';
+export { getEmbeddingAdapter, registerEmbeddingAdapter, hasEmbeddingAdapter, listEmbeddingAdapters, } from './registry.js';
+export { OpenAITextEmbedding3Small } from './adapters/openai-text-embedding-3-small.js';
+export type { EmbeddingCostCallback } from './adapters/openai-text-embedding-3-small.js';
+export type { EmbeddingStorageBackend, EmbeddingStaleVectorPolicy, VectorStoreEntry, VectorStoreFilter, } from './storage/types.js';
+export { JsonlEmbeddingStorageBackend, SCALE_ESCALATION_MAX_ENTRIES, SCALE_ESCALATION_P95_READ_MS, createEmbeddingStorageBackend, } from './storage/index.js';
+export type { ScaleEscalationSignal, StorageBackendName, StorageBackendOptions, } from './storage/index.js';
+export type { StaleVectorPolicy, StaleVectorPolicyInput, StaleVectorContext, StaleVectorDecisionSeverity, } from './stale-vector.js';
+export { FRAMEWORK_DEFAULT_STALE_VECTOR_POLICY, resolveStaleVectorPolicy, severityForPolicy, isCurrentVector, StaleVectorEncountered, } from './stale-vector.js';
+export type { ProviderCompatibility, CrossProviderDecisionPayload } from './cross-provider.js';
+export { checkProviderCompatibility, CrossProviderComparisonError, buildCrossProviderDecisionPayload, } from './cross-provider.js';
+export type { DeprecationLifecycleInput, DeprecationLifecycleResult, DeprecationDecisionEvent, DeprecationPhase, } from './deprecation.js';
+export { FRAMEWORK_DEFAULT_GRACE_PERIOD_DAYS, DEPRECATION_MILESTONE_DAYS, resolveGracePeriodDays, nextDueMilestone, buildDedupKey, evaluateDeprecationLifecycle, } from './deprecation.js';
+export { loadEmbeddingFromPipelineSpec, isEmbeddingFrameworkEnabled, resolveEffectiveGracePeriodDays, EMBEDDING_DEFAULTS, } from './pipeline-load.js';
+export type { EmbeddingSpecInput, ResolvedEmbedding, LoadEmbeddingOptions, DeprecationWarningEvent, } from './pipeline-load.js';
+export { TESSELLATION_DRIFT_CONSUMER_LABEL, TESSELLATION_DRIFT_STALE_VECTOR_POLICY, TESSELLATION_DRIFT_CONSUMER, embedDriftSignal, } from './consumers/tessellation-drift.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/embedding/index.js

@@ -0,0 +1,24 @@
+/**
+ * Embedding adapter framework per RFC-0019.
+ * Phase 1: interface + registry + OpenAI default adapter + errors.
+ * Phase 2: vector storage backend + JSONL default + backend factory + GC.
+ * Phase 3: stale-vector policy, cross-provider compatibility, deprecation
+ *          lifecycle (AISDLC-339). Migration tooling itself lives in
+ *          `pipeline-cli/src/cli/embedding-bump.ts`.
+ * Phase 4 (AISDLC-340): pipeline-load wiring + first-consumer (Eτ drift) spec stub.
+ *
+ * Phase 5 (soak) ships in AISDLC-341.
+ */
+export { EmbeddingError, UnknownEmbeddingProvider, EmbeddingProviderUnavailable, EmbeddingProviderError, EmbeddingDimensionMismatch, EmbeddingModelDeprecating, EmbeddingModelDeprecated, EmbeddingModelRemoved, } from './errors.js';
+export { getEmbeddingAdapter, registerEmbeddingAdapter, hasEmbeddingAdapter, listEmbeddingAdapters, } from './registry.js';
+export { OpenAITextEmbedding3Small } from './adapters/openai-text-embedding-3-small.js';
+export { JsonlEmbeddingStorageBackend, SCALE_ESCALATION_MAX_ENTRIES, SCALE_ESCALATION_P95_READ_MS, createEmbeddingStorageBackend, } from './storage/index.js';
+export { FRAMEWORK_DEFAULT_STALE_VECTOR_POLICY, resolveStaleVectorPolicy, severityForPolicy, isCurrentVector, StaleVectorEncountered, } from './stale-vector.js';
+export { checkProviderCompatibility, CrossProviderComparisonError, buildCrossProviderDecisionPayload, } from './cross-provider.js';
+export { FRAMEWORK_DEFAULT_GRACE_PERIOD_DAYS, DEPRECATION_MILESTONE_DAYS, resolveGracePeriodDays, nextDueMilestone, buildDedupKey, evaluateDeprecationLifecycle, } from './deprecation.js';
+// Phase 4 (AISDLC-340): pipeline-load wiring per RFC-0019 §10.1.
+export { loadEmbeddingFromPipelineSpec, isEmbeddingFrameworkEnabled, resolveEffectiveGracePeriodDays, EMBEDDING_DEFAULTS, } from './pipeline-load.js';
+// Phase 4 (AISDLC-340): first downstream consumer spec stub
+// (RFC-0009 Eτ_tessellation_drift — runtime usage activates when AISDLC-317 ships).
+export { TESSELLATION_DRIFT_CONSUMER_LABEL, TESSELLATION_DRIFT_STALE_VECTOR_POLICY, TESSELLATION_DRIFT_CONSUMER, embedDriftSignal, } from './consumers/tessellation-drift.js';
+//# sourceMappingURL=index.js.map

package/dist/embedding/pipeline-load.d.ts

@@ -0,0 +1,146 @@
+/**
+ * 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 type { EmbeddingStorageBackend } from './storage/types.js';
+import type { EmbeddingAdapter } from './types.js';
+/**
+ * Minimal subset of `Pipeline.spec.embedding` that pipeline-load reads.
+ * Defined here (rather than imported from `@ai-sdlc/reference`) to avoid
+ * a circular dependency — orchestrator already depends on reference,
+ * and reference must not depend on orchestrator.
+ */
+export interface EmbeddingSpecInput {
+    provider: string;
+    fallback?: string;
+    storageBackend?: string;
+    storageBackendConfig?: Record<string, unknown>;
+    staleVectorPolicy?: 'lazy-re-embed' | 'fail-loud' | 'warn';
+    autoEmbedOnWrite?: boolean;
+    maxBatchSize?: number;
+    deprecationOverrides?: {
+        gracePeriodDays?: number;
+        strictModeAtDeprecatedAt?: boolean;
+    };
+}
+/**
+ * Resolved embedding substrate returned by `loadEmbeddingFromPipelineSpec()`.
+ *
+ * Callers wire `adapter` into their embed() call sites and `storage` into
+ * their write/read paths. `staleVectorPolicy` is the per-org default;
+ * consumers MAY override at the API site per OQ-2 re-walkthrough.
+ */
+export interface ResolvedEmbedding {
+    adapter: EmbeddingAdapter;
+    /** Resolved fallback adapter (when distinct from primary). */
+    fallbackAdapter?: EmbeddingAdapter;
+    storage: EmbeddingStorageBackend;
+    /** Per-org default; consumers may pin a stricter policy at the API site. */
+    staleVectorPolicy: 'lazy-re-embed' | 'fail-loud' | 'warn';
+    autoEmbedOnWrite: boolean;
+    maxBatchSize: number;
+}
+/** Default values applied when fields are omitted from the spec. */
+export declare const EMBEDDING_DEFAULTS: {
+    readonly storageBackend: "jsonl";
+    readonly staleVectorPolicy: "lazy-re-embed";
+    readonly autoEmbedOnWrite: true;
+    readonly maxBatchSize: 2048;
+    /** Framework default; adapter MAY declare a different defaultGracePeriodDays. */
+    readonly gracePeriodDays: 90;
+};
+/** Options for the loader. */
+export interface LoadEmbeddingOptions {
+    /**
+     * Path to the artifacts directory. Used by the storage backend factory.
+     * Defaults to `process.env.ARTIFACTS_DIR ?? '.ai-sdlc/artifacts'`.
+     */
+    artifactsDir?: string;
+    /**
+     * Today, for deprecation-window math. Defaults to `new Date()`.
+     * Tests inject a fixed date so deprecation-gate behaviour is hermetic.
+     */
+    now?: Date;
+    /**
+     * Called when `AI_SDLC_EMBEDDING_PROVIDER` is OFF but a non-null spec
+     * was passed. Lets the orchestrator route the warning to events.jsonl
+     * or another logging surface without coupling the loader to a logger.
+     */
+    onFlagOffWithSpec?: (spec: EmbeddingSpecInput) => void;
+    /**
+     * Called when a deprecation WARNING fires (between adapter's effective
+     * `(deprecatedAt − gracePeriodDays)` and `deprecatedAt`). Operators
+     * SHOULD route this to the Decision catalog with milestone dedup.
+     */
+    onDeprecationWarning?: (event: DeprecationWarningEvent) => void;
+}
+/** Event surfaced by the deprecation gate during the warning window. */
+export interface DeprecationWarningEvent {
+    adapterName: string;
+    deprecatedAt: string;
+    removedAt?: string;
+    replacementAlias?: string;
+    daysUntilDeprecated: number;
+    /** Effective gracePeriodDays after applying three-layer precedence. */
+    effectiveGracePeriodDays: number;
+}
+/**
+ * `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 declare function isEmbeddingFrameworkEnabled(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * 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 declare function loadEmbeddingFromPipelineSpec(spec: EmbeddingSpecInput | null | undefined, options?: LoadEmbeddingOptions): ResolvedEmbedding | null;
+/**
+ * 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 declare function resolveEffectiveGracePeriodDays(adapter: EmbeddingAdapter, spec: EmbeddingSpecInput): number;
+//# sourceMappingURL=pipeline-load.d.ts.map