@ai-sdlc/orchestrator 0.9.0 → 0.13.0

package/dist/embedding/adapters/openai-text-embedding-3-small.js

@@ -0,0 +1,190 @@
+/**
+ * Default embedding adapter: openai-text-embedding-3-small per RFC-0019 §7.
+ *
+ * Model: text-embedding-3-small (OpenAI, snapshot 2024-01-25)
+ * Dimensions: 1536
+ * Max input: 8191 tokens
+ * Batch: up to 2048 inputs per call
+ * Billing: pay-per-token at ~$0.02 / 1M tokens
+ *
+ * Why text-embedding-3-small over -large:
+ * At $0.02/1M tokens, a 10K-token corpus re-embed costs ~$0.0002. The -large
+ * variant is 6.5x more expensive for marginal quality improvement on the
+ * short-text drift detection use case (RFC-0009 OQ-6). Adopters with
+ * quality-sensitive use cases MAY register the -large variant.
+ *
+ * Why snapshot 2024-01-25:
+ * Most recent stable snapshot as of RFC-0019 authoring. Pinning the snapshot
+ * date makes adapter upgrades a code change (visible in PR review) rather
+ * than a silent provider-side rollout. OpenAI has silently changed
+ * text-embedding-ada-002 behavior in the past — explicit pinning prevents that.
+ */
+import { createHash } from 'node:crypto';
+import { EmbeddingProviderError, EmbeddingDimensionMismatch } from '../errors.js';
+/** Cost rate for text-embedding-3-small as of 2024-01-25. */
+const COST_PER_TOKEN_USD = 0.02 / 1_000_000; // $0.02 per 1M tokens
+/** Maximum inputs per batch call (OpenAI API limit). */
+const MAX_BATCH_SIZE = 2048;
+export class OpenAITextEmbedding3Small {
+    name = 'openai-text-embedding-3-small';
+    modelId = 'text-embedding-3-small';
+    modelVersion = '2024-01-25';
+    dimensions = 1536;
+    capabilities = {
+        dimensions: 1536,
+        maxInputTokens: 8191,
+        supportsBatching: true,
+        selfHosted: false,
+        billingModel: 'pay-per-token',
+        approxCostPer1MTokens: 0.02,
+    };
+    requires = {
+        envVar: 'OPENAI_API_KEY',
+    };
+    /** Optional cost-tracking callback. Set by the orchestrator after adapter instantiation. */
+    costCallback;
+    constructor(costCallback) {
+        this.costCallback = costCallback;
+    }
+    /**
+     * Wire a cost-tracking callback after construction.
+     * Called by the orchestrator when it has a CostTracker available.
+     */
+    setCostCallback(callback) {
+        this.costCallback = callback;
+    }
+    async isAvailable() {
+        if (!process.env.OPENAI_API_KEY) {
+            return {
+                available: false,
+                reason: 'env-var-missing',
+                detail: 'OPENAI_API_KEY not set; openai-text-embedding-3-small requires it.',
+            };
+        }
+        return { available: true };
+    }
+    async getAccountId() {
+        const key = process.env.OPENAI_API_KEY;
+        if (!key)
+            return null;
+        // One-way derivation: SHA-256 of '<adapter-name>:<api-key>'.
+        // MUST NOT leak the credential.
+        return createHash('sha256').update(`${this.name}:${key}`).digest('hex');
+    }
+    /**
+     * Embed a single text string.
+     *
+     * @param text - Source text. MUST be non-empty.
+     * @param consumerLabel - Cost attribution label (default: 'unspecified').
+     *   Examples: 'rfc-0009-tessellation-drift', 'rfc-0008-ppa-similarity'.
+     */
+    async embed(text, consumerLabel = 'unspecified') {
+        if (!text || text.trim().length === 0) {
+            throw new EmbeddingProviderError(this.name, 'embed(): empty input rejected — pass non-empty text.');
+        }
+        const apiKey = process.env.OPENAI_API_KEY;
+        if (!apiKey) {
+            throw new EmbeddingProviderError(this.name, 'OPENAI_API_KEY is not set. Call isAvailable() before embed().');
+        }
+        const response = await fetch('https://api.openai.com/v1/embeddings', {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${apiKey}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                model: this.modelId,
+                input: text,
+                encoding_format: 'float',
+            }),
+        });
+        if (!response.ok) {
+            const body = await response.text().catch(() => '(unreadable)');
+            throw new EmbeddingProviderError(this.name, `OpenAI /v1/embeddings returned HTTP ${response.status}: ${body}`);
+        }
+        const data = (await response.json());
+        const vector = data.data[0]?.embedding;
+        if (!vector) {
+            throw new EmbeddingProviderError(this.name, 'OpenAI /v1/embeddings response contained no embedding in data[0].');
+        }
+        if (vector.length !== this.dimensions) {
+            throw new EmbeddingDimensionMismatch(this.name, this.dimensions, vector.length);
+        }
+        await this._recordCost(data.usage.total_tokens, consumerLabel);
+        return vector;
+    }
+    /**
+     * Embed a batch of texts.
+     * OpenAI accepts up to 2048 inputs per call; this method chunks above that.
+     * Input order is preserved in the returned array.
+     *
+     * @param texts - Array of source texts. Each MUST be non-empty.
+     * @param consumerLabel - Cost attribution label (applies to all texts in batch).
+     */
+    async embedBatch(texts, consumerLabel = 'unspecified') {
+        if (texts.length === 0) {
+            return [];
+        }
+        for (const t of texts) {
+            if (!t || t.trim().length === 0) {
+                throw new EmbeddingProviderError(this.name, 'embedBatch(): empty string in input array rejected — all texts must be non-empty.');
+            }
+        }
+        const apiKey = process.env.OPENAI_API_KEY;
+        if (!apiKey) {
+            throw new EmbeddingProviderError(this.name, 'OPENAI_API_KEY is not set. Call isAvailable() before embedBatch().');
+        }
+        const results = [];
+        // Chunk into MAX_BATCH_SIZE slices to respect the OpenAI API limit.
+        for (let i = 0; i < texts.length; i += MAX_BATCH_SIZE) {
+            const chunk = texts.slice(i, i + MAX_BATCH_SIZE);
+            const response = await fetch('https://api.openai.com/v1/embeddings', {
+                method: 'POST',
+                headers: {
+                    Authorization: `Bearer ${apiKey}`,
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({
+                    model: this.modelId,
+                    input: chunk,
+                    encoding_format: 'float',
+                }),
+            });
+            if (!response.ok) {
+                const body = await response.text().catch(() => '(unreadable)');
+                throw new EmbeddingProviderError(this.name, `OpenAI /v1/embeddings returned HTTP ${response.status} on batch chunk [${i}, ${i + chunk.length}): ${body}`);
+            }
+            const data = (await response.json());
+            // OpenAI returns data sorted by index — preserve input order.
+            const sorted = [...data.data].sort((a, b) => a.index - b.index);
+            for (const item of sorted) {
+                if (item.embedding.length !== this.dimensions) {
+                    throw new EmbeddingDimensionMismatch(this.name, this.dimensions, item.embedding.length);
+                }
+                results.push(item.embedding);
+            }
+            await this._recordCost(data.usage.total_tokens, consumerLabel);
+        }
+        return results;
+    }
+    /**
+     * Record a cost event via the cost callback.
+     * No-op when no callback is wired (e.g., in unit tests without a CostTracker).
+     */
+    async _recordCost(tokens, consumerLabel) {
+        if (!this.costCallback)
+            return;
+        const accountId = await this.getAccountId();
+        const costRecord = {
+            provider: this.name,
+            modelVersion: this.modelVersion,
+            accountId,
+            consumerLabel,
+            tokens,
+            costUsd: tokens * COST_PER_TOKEN_USD,
+            billingModel: 'pay-per-token',
+        };
+        this.costCallback(costRecord);
+    }
+}
+//# sourceMappingURL=openai-text-embedding-3-small.js.map

package/dist/embedding/consumers/tessellation-drift.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Spec-level wiring for the `Eτ_tessellation_drift` rule consumer per
+ * RFC-0009 Phase 4.2 / RFC-0019 Phase 4 (AISDLC-340).
+ *
+ * Runtime usage activates when RFC-0009 Phase 4.2 ships (AISDLC-317). The
+ * code here is the load-bearing API stub the runtime hooks call:
+ *
+ *   - `TESSELLATION_DRIFT_CONSUMER_LABEL` is the canonical `consumerLabel`
+ *     passed to `adapter.embed()` so cost-tracker records the
+ *     drift-attribution dimension per OQ-6 re-walkthrough.
+ *
+ *   - `TESSELLATION_DRIFT_STALE_VECTOR_POLICY` is the API-site override
+ *     per OQ-2 re-walkthrough: drift reads historical trajectory across
+ *     successive document revisions; lazy-re-embed is actively destructive
+ *     of that signal (silently overwrites old vectors → loses time-series
+ *     fidelity). The consumer pins `'fail-loud'` regardless of org default
+ *     to preserve historical-trajectory fidelity.
+ *
+ *   - `embedDriftSignal()` is the consumer-facing helper that wraps the
+ *     adapter's embed() call with the consumer label baked in. RFC-0009's
+ *     drift-computation pipeline calls THIS function, never adapter.embed()
+ *     directly, so the consumerLabel is impossible to forget at the call site.
+ *
+ * Tests: `tessellation-drift.test.ts`
+ */
+import type { EmbeddingAdapter } from '../types.js';
+import type { EmbeddingStaleVectorPolicy } from '../storage/types.js';
+/**
+ * Canonical consumer label for cost-tracker attribution. Per OQ-6
+ * re-walkthrough, callers pass this string so cost-tracker records the
+ * `(provider, modelVersion, accountId, consumerLabel='rfc-0009-tessellation-drift')`
+ * dimension and finance can answer "drift cost vs PPA cost" without
+ * re-instrumentation.
+ */
+export declare const TESSELLATION_DRIFT_CONSUMER_LABEL = "rfc-0009-tessellation-drift";
+/**
+ * API-site stale-vector policy override per OQ-2 re-walkthrough. The drift
+ * consumer pins `fail-loud` regardless of org default — silent re-embedding
+ * destroys the historical-trajectory signal the rule is measuring.
+ *
+ * Treat this constant as load-bearing: every drift-signal read site MUST
+ * read THIS value, not the org default, when deciding policy.
+ */
+export declare const TESSELLATION_DRIFT_STALE_VECTOR_POLICY: EmbeddingStaleVectorPolicy;
+/**
+ * Embed a single source text for the Eτ_tessellation_drift rule.
+ *
+ * RFC-0009's drift-computation pipeline (AISDLC-317, pending) calls THIS
+ * helper rather than `adapter.embed()` directly. The helper bakes in the
+ * consumer label so cost attribution is correct by construction.
+ *
+ * The adapter is passed in (not resolved here) because the orchestrator
+ * may have a fallback chain — the caller (pipeline runtime) decides which
+ * adapter to use; the consumer decides the LABEL and POLICY.
+ *
+ * @param adapter - Resolved embedding adapter (from `loadEmbeddingFromPipelineSpec`).
+ * @param text    - Source text to embed (a tessellation shard, typically).
+ * @returns       - Vector emitted by the adapter, length === adapter.dimensions.
+ */
+export declare function embedDriftSignal(adapter: EmbeddingAdapter, text: string): Promise<number[]>;
+/**
+ * Consumer descriptor exported for cross-cutting docs/registry purposes.
+ * Other consumers (PPA similarity, classifier embeddings, etc.) SHOULD
+ * export a similar descriptor so a future `cli-embedding-consumers list`
+ * can enumerate every consumer + its pinned policy.
+ */
+export declare const TESSELLATION_DRIFT_CONSUMER: {
+    readonly label: "rfc-0009-tessellation-drift";
+    readonly staleVectorPolicy: "fail-loud";
+    readonly rationale: string;
+    readonly rfc: "RFC-0009";
+    readonly task: "AISDLC-340";
+};
+//# sourceMappingURL=tessellation-drift.d.ts.map

package/dist/embedding/consumers/tessellation-drift.js

@@ -0,0 +1,76 @@
+/**
+ * Spec-level wiring for the `Eτ_tessellation_drift` rule consumer per
+ * RFC-0009 Phase 4.2 / RFC-0019 Phase 4 (AISDLC-340).
+ *
+ * Runtime usage activates when RFC-0009 Phase 4.2 ships (AISDLC-317). The
+ * code here is the load-bearing API stub the runtime hooks call:
+ *
+ *   - `TESSELLATION_DRIFT_CONSUMER_LABEL` is the canonical `consumerLabel`
+ *     passed to `adapter.embed()` so cost-tracker records the
+ *     drift-attribution dimension per OQ-6 re-walkthrough.
+ *
+ *   - `TESSELLATION_DRIFT_STALE_VECTOR_POLICY` is the API-site override
+ *     per OQ-2 re-walkthrough: drift reads historical trajectory across
+ *     successive document revisions; lazy-re-embed is actively destructive
+ *     of that signal (silently overwrites old vectors → loses time-series
+ *     fidelity). The consumer pins `'fail-loud'` regardless of org default
+ *     to preserve historical-trajectory fidelity.
+ *
+ *   - `embedDriftSignal()` is the consumer-facing helper that wraps the
+ *     adapter's embed() call with the consumer label baked in. RFC-0009's
+ *     drift-computation pipeline calls THIS function, never adapter.embed()
+ *     directly, so the consumerLabel is impossible to forget at the call site.
+ *
+ * Tests: `tessellation-drift.test.ts`
+ */
+/**
+ * Canonical consumer label for cost-tracker attribution. Per OQ-6
+ * re-walkthrough, callers pass this string so cost-tracker records the
+ * `(provider, modelVersion, accountId, consumerLabel='rfc-0009-tessellation-drift')`
+ * dimension and finance can answer "drift cost vs PPA cost" without
+ * re-instrumentation.
+ */
+export const TESSELLATION_DRIFT_CONSUMER_LABEL = 'rfc-0009-tessellation-drift';
+/**
+ * API-site stale-vector policy override per OQ-2 re-walkthrough. The drift
+ * consumer pins `fail-loud` regardless of org default — silent re-embedding
+ * destroys the historical-trajectory signal the rule is measuring.
+ *
+ * Treat this constant as load-bearing: every drift-signal read site MUST
+ * read THIS value, not the org default, when deciding policy.
+ */
+export const TESSELLATION_DRIFT_STALE_VECTOR_POLICY = 'fail-loud';
+/**
+ * Embed a single source text for the Eτ_tessellation_drift rule.
+ *
+ * RFC-0009's drift-computation pipeline (AISDLC-317, pending) calls THIS
+ * helper rather than `adapter.embed()` directly. The helper bakes in the
+ * consumer label so cost attribution is correct by construction.
+ *
+ * The adapter is passed in (not resolved here) because the orchestrator
+ * may have a fallback chain — the caller (pipeline runtime) decides which
+ * adapter to use; the consumer decides the LABEL and POLICY.
+ *
+ * @param adapter - Resolved embedding adapter (from `loadEmbeddingFromPipelineSpec`).
+ * @param text    - Source text to embed (a tessellation shard, typically).
+ * @returns       - Vector emitted by the adapter, length === adapter.dimensions.
+ */
+export async function embedDriftSignal(adapter, text) {
+    return adapter.embed(text, TESSELLATION_DRIFT_CONSUMER_LABEL);
+}
+/**
+ * Consumer descriptor exported for cross-cutting docs/registry purposes.
+ * Other consumers (PPA similarity, classifier embeddings, etc.) SHOULD
+ * export a similar descriptor so a future `cli-embedding-consumers list`
+ * can enumerate every consumer + its pinned policy.
+ */
+export const TESSELLATION_DRIFT_CONSUMER = {
+    label: TESSELLATION_DRIFT_CONSUMER_LABEL,
+    staleVectorPolicy: TESSELLATION_DRIFT_STALE_VECTOR_POLICY,
+    rationale: 'Eτ drift reads historical trajectory across successive document revisions; ' +
+        'lazy-re-embed silently overwrites old vectors and destroys the time-series signal. ' +
+        'Pin fail-loud at the API site (RFC-0019 OQ-2 re-walkthrough).',
+    rfc: 'RFC-0009',
+    task: 'AISDLC-340',
+};
+//# sourceMappingURL=tessellation-drift.js.map

package/dist/embedding/cross-provider.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Cross-provider compatibility per RFC-0019 §9.3 + OQ-3 re-walkthrough split.
+ *
+ * The OQ-3 re-walkthrough resolution surfaces a critical distinction that
+ * v0.2 missed: cross-PROVIDER comparisons (openai vs cohere) are NEVER valid
+ * because the math is genuinely undefined — vectors in different embedding
+ * spaces have no metrically-valid distance. cross-VERSION-within-provider
+ * comparisons (3-small@2024-01-25 vs 3-small@2025-01-25) DELEGATE to the
+ * stale-vector policy because closely-correlated embedding spaces support
+ * lazy re-embed.
+ *
+ * Policy mapping:
+ *
+ *   stored.provider != current.provider  → ALWAYS REFUSE + emit
+ *                                          `Decision: cross-provider-comparison-attempted`
+ *                                          → auto-action: emit cli-embedding-bump
+ *                                            migration task
+ *
+ *   stored.provider == current.provider
+ *   AND
+ *   stored.modelVersion != current.modelVersion → DELEGATE to staleVectorPolicy
+ *
+ *   stored matches current entirely               → COMPATIBLE (no policy)
+ *
+ * This resolves v0.2's logical conflict where both cases were lumped under
+ * "strict no-op" contradicting OQ-2's lazy-re-embed default.
+ *
+ * @module embedding/cross-provider
+ */
+import { EmbeddingError } from './errors.js';
+/**
+ * The three possible outcomes of a provider-compatibility check.
+ *
+ *  - `compatible`               — same provider AND same model version. Caller
+ *                                 may compare vectors directly.
+ *  - `cross-version`            — same provider, different model version.
+ *                                 Caller MUST consult the stale-vector policy.
+ *  - `cross-provider`           — different provider. Caller MUST refuse the
+ *                                 comparison and emit a catalog Decision +
+ *                                 migration task.
+ */
+export type ProviderCompatibility = 'compatible' | 'cross-version' | 'cross-provider';
+/**
+ * Compare a stored entry's provenance against the currently configured adapter.
+ * Pure function — no side effects, no event emission. Callers wrap the result
+ * with their own catalog logging.
+ */
+export declare function checkProviderCompatibility(storedProvider: string, storedModelVersion: string, currentProvider: string, currentModelVersion: string): ProviderCompatibility;
+/**
+ * Thrown when a cross-PROVIDER comparison is attempted (e.g., openai vs cohere).
+ * Always fatal — the math is undefined and there is no auto-migration path.
+ * Operators must run cli-embedding-bump to re-embed the entire corpus on the
+ * new provider.
+ */
+export declare class CrossProviderComparisonError extends EmbeddingError {
+    readonly storedProvider: string;
+    readonly currentProvider: string;
+    readonly textHash?: string | undefined;
+    constructor(storedProvider: string, currentProvider: string, textHash?: string | undefined);
+}
+/**
+ * Build the catalog Decision payload for a cross-provider attempt per
+ * RFC-0019 §9.3 OQ-3 re-walkthrough. The caller forwards this to
+ * `appendDecisionEvent()` so a `Decision: cross-provider-comparison-attempted`
+ * lands in the catalog and the operator gets a migration task.
+ */
+export interface CrossProviderDecisionPayload {
+    /** Stable summary used as the catalog Decision summary. */
+    summary: string;
+    /** Suggested migration command. */
+    migrationCommand: string;
+    /** Severity — always high for cross-provider. */
+    severity: 'high';
+    /** Auto-action — always emit a cli-embedding-bump migration task. */
+    autoAction: 'emit-migration-task';
+}
+export declare function buildCrossProviderDecisionPayload(storedProvider: string, currentProvider: string): CrossProviderDecisionPayload;
+//# sourceMappingURL=cross-provider.d.ts.map

package/dist/embedding/cross-provider.js

@@ -0,0 +1,75 @@
+/**
+ * Cross-provider compatibility per RFC-0019 §9.3 + OQ-3 re-walkthrough split.
+ *
+ * The OQ-3 re-walkthrough resolution surfaces a critical distinction that
+ * v0.2 missed: cross-PROVIDER comparisons (openai vs cohere) are NEVER valid
+ * because the math is genuinely undefined — vectors in different embedding
+ * spaces have no metrically-valid distance. cross-VERSION-within-provider
+ * comparisons (3-small@2024-01-25 vs 3-small@2025-01-25) DELEGATE to the
+ * stale-vector policy because closely-correlated embedding spaces support
+ * lazy re-embed.
+ *
+ * Policy mapping:
+ *
+ *   stored.provider != current.provider  → ALWAYS REFUSE + emit
+ *                                          `Decision: cross-provider-comparison-attempted`
+ *                                          → auto-action: emit cli-embedding-bump
+ *                                            migration task
+ *
+ *   stored.provider == current.provider
+ *   AND
+ *   stored.modelVersion != current.modelVersion → DELEGATE to staleVectorPolicy
+ *
+ *   stored matches current entirely               → COMPATIBLE (no policy)
+ *
+ * This resolves v0.2's logical conflict where both cases were lumped under
+ * "strict no-op" contradicting OQ-2's lazy-re-embed default.
+ *
+ * @module embedding/cross-provider
+ */
+import { EmbeddingError } from './errors.js';
+/**
+ * Compare a stored entry's provenance against the currently configured adapter.
+ * Pure function — no side effects, no event emission. Callers wrap the result
+ * with their own catalog logging.
+ */
+export function checkProviderCompatibility(storedProvider, storedModelVersion, currentProvider, currentModelVersion) {
+    if (storedProvider !== currentProvider) {
+        return 'cross-provider';
+    }
+    if (storedModelVersion !== currentModelVersion) {
+        return 'cross-version';
+    }
+    return 'compatible';
+}
+/**
+ * Thrown when a cross-PROVIDER comparison is attempted (e.g., openai vs cohere).
+ * Always fatal — the math is undefined and there is no auto-migration path.
+ * Operators must run cli-embedding-bump to re-embed the entire corpus on the
+ * new provider.
+ */
+export class CrossProviderComparisonError extends EmbeddingError {
+    storedProvider;
+    currentProvider;
+    textHash;
+    constructor(storedProvider, currentProvider, textHash) {
+        super(`Cross-provider comparison refused: stored vector is from '${storedProvider}', ` +
+            `current adapter is '${currentProvider}'. Embedding spaces are not metrically ` +
+            `comparable across providers. Migrate via: cli-embedding-bump --to ${currentProvider}` +
+            (textHash ? ` (offending textHash: ${textHash})` : ''));
+        this.storedProvider = storedProvider;
+        this.currentProvider = currentProvider;
+        this.textHash = textHash;
+        this.name = 'CrossProviderComparisonError';
+    }
+}
+export function buildCrossProviderDecisionPayload(storedProvider, currentProvider) {
+    return {
+        summary: `Cross-provider comparison attempted: '${storedProvider}' vs '${currentProvider}'. ` +
+            `Refused (math undefined). Run cli-embedding-bump to migrate.`,
+        migrationCommand: `cli-embedding-bump --to ${currentProvider}`,
+        severity: 'high',
+        autoAction: 'emit-migration-task',
+    };
+}
+//# sourceMappingURL=cross-provider.js.map

package/dist/embedding/deprecation.d.ts

@@ -0,0 +1,151 @@
+/**
+ * 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 declare 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 declare const DEPRECATION_MILESTONE_DAYS: ReadonlyArray<number>;
+/**
+ * Inputs to the deprecation lifecycle evaluator.
+ * `today` defaults to the current date; callers pass an explicit Date in tests.
+ */
+export interface DeprecationLifecycleInput {
+    /** Canonical adapter name (e.g., 'openai-text-embedding-ada-002'). */
+    adapterName: string;
+    /** ISO date when the deprecation warning period starts (adapter.deprecatedAt). */
+    deprecatedAt?: string;
+    /** ISO date when the adapter is removed (adapter.removedAt). */
+    removedAt?: string;
+    /** Canonical replacement alias for migration messaging. */
+    replacementAlias?: string;
+    /** Adapter-declared default grace period override. */
+    adapterDefaultGracePeriodDays?: number;
+    /** Per-org override from embedding-config.yaml. */
+    orgGracePeriodDays?: number;
+    /** Whether the operator runs in strict mode (escalate severity at deprecatedAt). */
+    strictModeAtDeprecatedAt?: boolean;
+    /** Override "today" for deterministic tests. */
+    today?: Date;
+}
+/**
+ * Lifecycle phase the adapter is currently in.
+ */
+export type DeprecationPhase = 'pre-warning' | 'warning' | 'deprecated' | 'removed' | 'inactive';
+/**
+ * One catalog Decision event the caller should append.
+ */
+export interface DeprecationDecisionEvent {
+    /** RFC-0035 catalog Decision type. */
+    decisionType: 'embedding-provider-deprecated' | 'embedding-provider-removed';
+    /** Dedup key — caller MUST refuse duplicate emissions for the same key. */
+    dedupKey: string;
+    /** Catalog severity. */
+    severity: 'info' | 'high';
+    /** Human-readable summary used as the Decision summary. */
+    summary: string;
+    /** Milestone reached, in days-before-deprecatedAt. Null for `removed` events. */
+    milestoneDaysBefore: number | null;
+    /**
+     * Auto-action the orchestrator MUST perform when this event lands.
+     * `null` for milestone events that don't auto-trigger anything.
+     */
+    autoAction: 'emit-migration-task' | null;
+}
+/**
+ * Result of evaluating the deprecation lifecycle for one adapter at one point
+ * in time.
+ */
+export interface DeprecationLifecycleResult {
+    /** Current phase. */
+    phase: DeprecationPhase;
+    /** Effective grace period used (after three-layer precedence). */
+    effectiveGracePeriodDays: number;
+    /** Days from today to deprecatedAt (negative if past). Null when undeclared. */
+    daysToDeprecatedAt: number | null;
+    /** Days from today to removedAt (negative if past). Null when undeclared. */
+    daysToRemovedAt: number | null;
+    /**
+     * Decision events the caller should emit. May be empty (phase == pre-warning
+     * OR no milestone was crossed in the current load).
+     *
+     * The caller is responsible for catalog dedup — DO NOT emit when the dedup
+     * key has already been seen. See {@link DeprecationDecisionEvent.dedupKey}.
+     */
+    decisionEvents: DeprecationDecisionEvent[];
+}
+/**
+ * Resolve the effective grace period using the three-layer precedence chain
+ * per OQ-4 re-walkthrough.
+ */
+export declare function resolveGracePeriodDays(orgOverride: number | undefined, adapterDefault: number | undefined): number;
+/**
+ * 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 declare function nextDueMilestone(daysToDeprecatedAt: number): number | 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 declare function buildDedupKey(decisionType: DeprecationDecisionEvent['decisionType'], adapterName: string, deprecatedAt: string | undefined, milestoneDaysBefore: number | null): string;
+/**
+ * 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 declare function evaluateDeprecationLifecycle(input: DeprecationLifecycleInput): DeprecationLifecycleResult;
+//# sourceMappingURL=deprecation.d.ts.map