@ai-sdlc/orchestrator 0.10.0 → 0.13.0

package/dist/compliance-clearance.js

@@ -0,0 +1,269 @@
+/**
+ * RFC-0009 Phase 4.1 — Eρ₅ Compliance Clearance scoring.
+ *
+ * Implements the categorical 0/1 gating dimension from RFC-0009 §7.1:
+ *
+ *   Eρ₅ = soul.triad.engineering.complianceRegimes[].clearance(work_item)
+ *       = 0 if any named regime is violated
+ *       = 1 otherwise
+ *
+ * **OQ-5 scope** (v3.3 resolution, 2026-05-03): HARD regulatory frameworks
+ * ONLY — anything with formal external-audit consequences. Internal best
+ * practices, code style, architectural preferences, and team conventions are
+ * OUT OF SCOPE and rejected at declaration time per the boundary test:
+ * "would an external regulator or auditor have grounds to act on a violation?"
+ *
+ *   In scope:
+ *     - GDPR (EU data protection)
+ *     - HIPAA (US healthcare)
+ *     - SOC2 (audit trust framework — variants like SOC2-T2 accepted)
+ *     - PCI-DSS (payment card data — variants like PCI-DSS-L1 accepted)
+ *     - FedRAMP (US federal cloud — variants like FedRAMP-Moderate accepted)
+ *     - Regional data-residency (Schrems II, EU data-localization, China PIPL,
+ *       Canadian PIPEDA cross-border)
+ *     - Regulated-industry rules (financial KYC/AML, healthcare device
+ *       certification, telecom regulations, ISO-27001 audit framework, etc.)
+ *
+ *   Out of scope (rejected at declaration time):
+ *     - Internal best-practices ("clean-code", "team-style", "house-style")
+ *     - Code-quality rules ("eslint-recommended", "prettier-standard")
+ *     - Architectural preferences ("hexagonal", "ddd-strict")
+ *     - Team conventions ("our-conventions", "internal-coding-standard")
+ *
+ * **Adopter opt-in gate** (RFC-0009 §10 Phase 4): Eρ₅ is gated behind
+ * `ComplianceClearanceContext.enabled === true` initially. Promotion to
+ * default behavior is subject to ecosystem feedback. When disabled (default),
+ * the admission composite does not apply the Eρ₅ multiplier and behaves
+ * exactly as in Phase 2/3 — full backward compatibility.
+ *
+ * **RFC-0022 consumption surface**: when an adopter wires the loaded
+ * `CompliancePosture[]` into `ComplianceClearanceContext.posture`, the
+ * declared regimes from that resource compose with the soul's own
+ * `complianceRegimes` field. Both sources contribute to the regime set
+ * the work item is checked against; clearance is gating across the union.
+ *
+ * @see spec/rfcs/RFC-0009-tessellated-design-intent-documents.md §7.1 + §10
+ * @see spec/rfcs/RFC-0022-compliance-posture-audit-surface.md (consumption surface)
+ */
+// ── Hard-regulatory whitelist (OQ-5 scope) ─────────────────────────────
+/**
+ * Canonical hard-regulatory framework prefixes per RFC-0009 §7.1 OQ-5 resolution.
+ *
+ * Matching is **prefix-based** to accept variants like `SOC2-T2`, `PCI-DSS-L1`,
+ * `FedRAMP-Moderate`, `FedRAMP-High`, `ISO-27001:2022`. The exact framework name
+ * (without tier/version suffix) is the prefix; anything starting with one of
+ * these prefixes is considered a hard-regulatory regime.
+ *
+ * Regional data-residency frameworks (Schrems II / PIPL / PIPEDA) are listed
+ * explicitly. Generic `DATA-RESIDENCY-*` prefix is also accepted for adopters
+ * who declare per-region constraints under a unified naming scheme.
+ */
+export const HARD_REGULATORY_REGIME_PREFIXES = Object.freeze([
+    // ── Core US/EU/global frameworks ────────────────────────────────────
+    'GDPR', // EU General Data Protection Regulation
+    'HIPAA', // US Health Insurance Portability and Accountability Act
+    'SOC2', // Service Organization Control 2 (T1 / T2 variants)
+    'PCI-DSS', // Payment Card Industry Data Security Standard (L1-L4 variants)
+    'FedRAMP', // US Federal Risk and Authorization Management Program
+    'ISO-27001', // ISO/IEC 27001 Information Security Management Systems
+    // ── Regional data-residency frameworks ──────────────────────────────
+    'PIPL', // China Personal Information Protection Law
+    'PIPEDA', // Canadian Personal Information Protection and Electronic Documents Act
+    'SCHREMS-II', // EU Schrems II ruling (cross-border data transfers)
+    'DATA-RESIDENCY', // Generic regional residency declaration
+    // ── Regulated-industry rules ────────────────────────────────────────
+    'KYC', // Know-Your-Customer (financial services)
+    'AML', // Anti-Money Laundering (financial services)
+    'GLBA', // Gramm-Leach-Bliley Act (US financial privacy)
+    'SOX', // Sarbanes-Oxley Act (US public-company audit)
+    'NERC-CIP', // North American Electric Reliability Corp. Critical Infrastructure Protection
+    'FDA-21CFR11', // FDA 21 CFR Part 11 (regulated healthcare/pharma device)
+    'CCPA', // California Consumer Privacy Act (state-level, regulator-enforced)
+    'CPRA', // California Privacy Rights Act (CCPA successor)
+]);
+/**
+ * Predicate: returns true iff the regime ID matches a hard-regulatory prefix
+ * per the OQ-5 scope whitelist.
+ *
+ * Comparison is case-insensitive on the regime ID (`HIPAA` and `hipaa` both
+ * match) but the canonical prefixes are uppercase by convention.
+ *
+ * **Boundary guard (AISDLC-316 round-2 code-review fix)**: a match requires the
+ * prefix to be either the WHOLE regime id OR followed by a separator
+ * (`-`, `_`, `:`, `.`) or a digit (tier-variant pattern). This prevents
+ * collision-prone soft regimes like `SOXophone`, `AMLET`, `KYCS-internal`,
+ * `HIPAAphobia` from being mis-classified as hard-regulatory by a naive
+ * `startsWith` check. Tier-variants like `SOC2-T2`, `PCI-DSS-L1`,
+ * `FedRAMP-Moderate`, `ISO-27001:2022`, `SOC2T2` (digit boundary) still match.
+ *
+ * @example
+ *   isHardRegulatoryRegime('HIPAA')           // true
+ *   isHardRegulatoryRegime('SOC2-T2')         // true (SOC2 prefix + '-' boundary)
+ *   isHardRegulatoryRegime('PCI-DSS-L1')      // true (PCI-DSS prefix + '-' boundary)
+ *   isHardRegulatoryRegime('FedRAMP-Moderate')// true (FedRAMP prefix + '-' boundary)
+ *   isHardRegulatoryRegime('ISO-27001:2022')  // true (ISO-27001 prefix + ':' boundary)
+ *   isHardRegulatoryRegime('clean-code')      // false (soft / out of scope)
+ *   isHardRegulatoryRegime('team-style')      // false (soft / out of scope)
+ *   isHardRegulatoryRegime('SOXophone')       // false (SOX prefix but letter boundary)
+ *   isHardRegulatoryRegime('AMLET')           // false (AML prefix but letter boundary)
+ *   isHardRegulatoryRegime('HIPAAphobia')     // false (HIPAA prefix but letter boundary)
+ */
+export function isHardRegulatoryRegime(regimeId) {
+    if (typeof regimeId !== 'string' || regimeId.length === 0)
+        return false;
+    const upper = regimeId.toUpperCase();
+    return HARD_REGULATORY_REGIME_PREFIXES.some((prefix) => {
+        const upperPrefix = prefix.toUpperCase();
+        if (!upper.startsWith(upperPrefix))
+            return false;
+        // Whole-id match → accept.
+        if (upper.length === upperPrefix.length)
+            return true;
+        // Boundary char must be a separator or a digit (tier/version variant).
+        // Letters following the prefix would be a soft-regime collision (e.g.
+        // SOXophone, AMLET, HIPAAphobia) and MUST NOT match.
+        const next = upper.charCodeAt(upperPrefix.length);
+        // '-' = 45, '_' = 95, ':' = 58, '.' = 46, '0'-'9' = 48-57
+        return (next === 45 || // '-'
+            next === 95 || // '_'
+            next === 58 || // ':'
+            next === 46 || // '.'
+            (next >= 48 && next <= 57) // digit
+        );
+    });
+}
+/**
+ * Validate a list of declared compliance regimes against the OQ-5 hard-regulatory
+ * scope. Used at declaration time (DID load, RFC-0022 posture parse) to reject
+ * soft regimes before they reach the Eρ₅ scoring path.
+ *
+ * Per RFC-0009 OQ-5 sub-decision: soft/advisory regimes are NOT in scope and
+ * MUST be filtered at declaration time. Internal best-practices, code style,
+ * and team conventions belong to other mechanisms (code review, lint).
+ *
+ * @param regimes - Declared regime IDs from a soul's `complianceRegimes`
+ *                  field or an RFC-0022 `CompliancePosture.spec.regimes[].id`.
+ * @returns Validation result with split accepted/rejected lists.
+ */
+export function validateComplianceRegimes(regimes) {
+    if (!regimes || regimes.length === 0) {
+        return { valid: true, accepted: [], rejected: [] };
+    }
+    const accepted = [];
+    const rejected = [];
+    for (const r of regimes) {
+        if (isHardRegulatoryRegime(r))
+            accepted.push(r);
+        else
+            rejected.push(r);
+    }
+    return { valid: rejected.length === 0, accepted, rejected };
+}
+// ── Core scoring function ──────────────────────────────────────────────
+/**
+ * Compute Eρ₅ Compliance Clearance for a work item.
+ *
+ * Algorithm (RFC-0009 §7.1 + §10 Phase 4):
+ * 1. If `ctx.enabled !== true` → return `er5 = 1` with `routingPath = 'disabled'`.
+ * 2. Build the regime set from:
+ *    - Each soul in `affectedSoulIds`'s `perSoulRegimes` entry, OR
+ *      the `__platform` sentinel entry when `affectedSoulIds` is empty.
+ *    - All RFC-0022 posture regimes (if `ctx.posture` present).
+ *    Filter through `isHardRegulatoryRegime` (defense-in-depth on the OQ-5 boundary).
+ * 3. If regime set is empty → `er5 = 1`, `routingPath = 'no-regimes'`.
+ * 4. Look up violations for `workItemId` in `ctx.violations` (case-insensitive).
+ *    Filter to violations whose `regimeId` is in the regime set.
+ *    - If any remain → `er5 = 0`, `routingPath = 'clearance-violated'`.
+ *    - Else → `er5 = 1`, `routingPath = 'clearance-holds'`.
+ *
+ * @param workItemId        - Canonical work item ID (e.g. `AISDLC-316`).
+ * @param affectedSoulIds   - Soul IDs the work item targets (from
+ *                            `resolveAffectedSouls()`). Empty array =
+ *                            non-tessellated or substrate-only; uses
+ *                            `__platform` sentinel.
+ * @param ctx               - Compliance clearance context (or undefined =
+ *                            treated as disabled).
+ * @returns Eρ₅ clearance result with routing audit trail.
+ */
+export function computeComplianceClearance(workItemId, affectedSoulIds, ctx) {
+    // ── Opt-in gate ────────────────────────────────────────────────
+    if (!ctx || ctx.enabled !== true) {
+        return {
+            er5: 1,
+            routingPath: 'disabled',
+            checkedRegimes: [],
+            violations: [],
+        };
+    }
+    // ── Build the regime set ───────────────────────────────────────
+    // Set keys are stored as UPPER-CASE canonical form so that case-collisions
+    // between declaration and violation reporting do not silently drop a
+    // gating violation. AISDLC-316 round-2 code-review MAJOR #1 fix: previously
+    // a soul declaring `['hipaa']` and an enforcement plugin asserting
+    // `regimeId: 'HIPAA'` failed the `regimeSet.has(v.regimeId)` lookup
+    // (case-sensitive `Set.has`) → violation silently dropped → composite NOT
+    // gated. Normalising both sides to uppercase is the defense.
+    // `displayCheckedRegimes` preserves the original (first-seen) casing so
+    // the audit trail shown in `checkedRegimes` stays human-friendly.
+    const regimeSet = new Set();
+    const displayCheckedRegimes = [];
+    function addRegime(rawId) {
+        if (!isHardRegulatoryRegime(rawId))
+            return;
+        const upper = rawId.toUpperCase();
+        if (regimeSet.has(upper))
+            return;
+        regimeSet.add(upper);
+        displayCheckedRegimes.push(rawId);
+    }
+    // Soul-declared regimes — use affectedSoulIds when present, else __platform.
+    const soulIdsToCheck = affectedSoulIds.length === 0 ? ['__platform'] : affectedSoulIds;
+    for (const soulId of soulIdsToCheck) {
+        const entry = ctx.perSoulRegimes.find((e) => e.soulId === soulId);
+        if (!entry)
+            continue;
+        for (const r of entry.regimes) {
+            addRegime(r);
+        }
+    }
+    // RFC-0022 posture regimes — added across the union.
+    if (ctx.posture && ctx.posture.length > 0) {
+        for (const posture of ctx.posture) {
+            for (const regime of posture.spec.regimes ?? []) {
+                addRegime(regime.id);
+            }
+        }
+    }
+    const checkedRegimes = displayCheckedRegimes;
+    // ── No regimes apply ───────────────────────────────────────────
+    if (checkedRegimes.length === 0) {
+        return {
+            er5: 1,
+            routingPath: 'no-regimes',
+            checkedRegimes: [],
+            violations: [],
+        };
+    }
+    // ── Look up violations for this work item ──────────────────────
+    // Violation regimeId is normalised to UPPER-CASE before lookup so that a
+    // soul declaring `['hipaa']` matches an enforcement plugin asserting
+    // `regimeId: 'HIPAA'` (and vice versa). AISDLC-316 round-2 fix.
+    const normalizedId = workItemId.toLowerCase();
+    const entry = ctx.violations?.find((e) => e.id.toLowerCase() === normalizedId);
+    const applicableViolations = entry?.violations.filter((v) => typeof v.regimeId === 'string' && regimeSet.has(v.regimeId.toUpperCase())) ?? [];
+    if (applicableViolations.length > 0) {
+        return {
+            er5: 0,
+            routingPath: 'clearance-violated',
+            checkedRegimes,
+            violations: applicableViolations,
+        };
+    }
+    return {
+        er5: 1,
+        routingPath: 'clearance-holds',
+        checkedRegimes,
+        violations: [],
+    };
+}
+//# sourceMappingURL=compliance-clearance.js.map

package/dist/config.js

@@ -46,6 +46,23 @@ export function loadConfig(configDir) {
             continue;
         }
         const result = validateResource(doc);
+        if (result.skipped) {
+            // AISDLC-265 PR #474 review fix: skipped kinds get an INFO-level warning
+            // entry so typo'd canonical kinds (e.g. `kind: AutonomyPolcy` instead of
+            // `AutonomyPolicy`) don't silently disappear. The legitimate loader-private
+            // kinds (MaintainersList, SoulTrackMap) appear in this list too, but
+            // operators can recognise them and ignore — the dangerous case before the
+            // fix was a silent drop with NO surface, which let security-relevant
+            // misconfigurations (typo'd AutonomyPolicy → no policy loaded → permissive
+            // defaults) ship undetected. See docs/operations/schema-extensions.md.
+            const docKind = doc.kind;
+            const kindStr = typeof docKind === 'string' ? docKind : String(docKind);
+            warnings.push({
+                file,
+                error: `unknown kind '${kindStr}' — skipped (loader-private convention or typo of canonical kind?)`,
+            });
+            continue;
+        }
         if (!result.valid) {
             const msgs = (result.errors ?? []).map((e) => `${e.path}: ${e.message}`).join('; ');
             // Forward-looking schemas are common during incremental adoption

package/dist/cost-tracker.d.ts

@@ -3,9 +3,15 @@
  * and tracks budget status.
  *
  * RFC reference: Lines 618-720 (cost tracking).
+ *
+ * RFC-0019 §10 / AISDLC-337: embeddingTokens line item added via
+ * recordEmbeddingCost(). Embedding costs are recorded with
+ * pipelineType='embeddingTokens' and do NOT decrement SubscriptionLedger
+ * window quota when adapter billingModel='pay-per-token' (OQ-7 re-walkthrough).
  */
 import type { StateStore } from './state/store.js';
 import type { CostLedgerEntry } from './state/types.js';
+import type { EmbeddingCostRecord } from './embedding/types.js';
 export interface CostSummary {
     totalCostUsd: number;
     totalTokens: number;
@@ -71,5 +77,21 @@ export declare class CostTracker {
      * Get cost time series at a given granularity.
      */
     getCostTimeSeries(granularity?: 'day' | 'week' | 'month', since?: string): CostTimeSeriesPoint[];
+    /**
+     * Record an embedding cost event per RFC-0019 §10 / AISDLC-337.
+     *
+     * Records a 'embeddingTokens' line item in the cost ledger with full
+     * (provider, modelVersion, accountId, consumerLabel) attribution dimensions
+     * per OQ-6 re-walkthrough.
+     *
+     * When adapter.billingModel === 'pay-per-token', the cost is recorded
+     * but does NOT consume SubscriptionLedger window quota (OQ-7 re-walkthrough).
+     * When billingModel === 'subscription-quota', callers must separately update
+     * the SubscriptionLedger via the inputTokens/outputTokens mechanism.
+     *
+     * @param record - Embedding cost attribution data from the adapter.
+     * @param runId - Pipeline run ID for traceability (optional; defaults to 'embedding').
+     */
+    recordEmbeddingCost(record: EmbeddingCostRecord, runId?: string): number;
 }
 //# sourceMappingURL=cost-tracker.d.ts.map

package/dist/cost-tracker.js

@@ -3,6 +3,11 @@
  * and tracks budget status.
  *
  * RFC reference: Lines 618-720 (cost tracking).
+ *
+ * RFC-0019 §10 / AISDLC-337: embeddingTokens line item added via
+ * recordEmbeddingCost(). Embedding costs are recorded with
+ * pipelineType='embeddingTokens' and do NOT decrement SubscriptionLedger
+ * window quota when adapter billingModel='pay-per-token' (OQ-7 re-walkthrough).
  */
 import { DEFAULT_MODEL_COSTS, DEFAULT_COST_BUDGET_USD } from './defaults.js';
 export class CostTracker {
@@ -173,5 +178,41 @@ export class CostTracker {
         }
         return [...buckets.values()].sort((a, b) => a.date.localeCompare(b.date));
     }
+    /**
+     * Record an embedding cost event per RFC-0019 §10 / AISDLC-337.
+     *
+     * Records a 'embeddingTokens' line item in the cost ledger with full
+     * (provider, modelVersion, accountId, consumerLabel) attribution dimensions
+     * per OQ-6 re-walkthrough.
+     *
+     * When adapter.billingModel === 'pay-per-token', the cost is recorded
+     * but does NOT consume SubscriptionLedger window quota (OQ-7 re-walkthrough).
+     * When billingModel === 'subscription-quota', callers must separately update
+     * the SubscriptionLedger via the inputTokens/outputTokens mechanism.
+     *
+     * @param record - Embedding cost attribution data from the adapter.
+     * @param runId - Pipeline run ID for traceability (optional; defaults to 'embedding').
+     */
+    recordEmbeddingCost(record, runId = 'embedding') {
+        // Encoding convention for embeddingTokens line items:
+        //   pipelineType = 'embeddingTokens'  ← discriminates from LLM entries
+        //   agentName    = consumerLabel       ← per-consumer attribution (OQ-6)
+        //   model        = provider@modelVersion ← identifies exact model snapshot
+        //   inputTokens  = tokens              ← total embedding tokens consumed
+        //   costUsd      = pre-computed by adapter ← $0.02/1M for OpenAI small
+        //   stageName    = accountId (or 'self-hosted') ← per-credential attribution
+        const entry = {
+            runId,
+            agentName: record.consumerLabel,
+            pipelineType: 'embeddingTokens',
+            model: `${record.provider}@${record.modelVersion}`,
+            inputTokens: record.tokens,
+            outputTokens: 0,
+            totalTokens: record.tokens,
+            costUsd: record.costUsd,
+            stageName: record.accountId ?? 'self-hosted',
+        };
+        return this.store.saveCostEntry(entry);
+    }
 }
 //# sourceMappingURL=cost-tracker.js.map

package/dist/database/adapters/external.js

@@ -43,7 +43,11 @@ export class ExternalAdapter {
         const exec = this.deps.exec ?? ((c, a) => execFileAsync(c, a));
         let stdout;
         try {
-            const result = await exec('sh', ['-c', `${cmd} ${branchKey}`]);
+            // Pass branchKey as positional $1 (not string-interpolated) so the shell
+            // quotes it safely — `cmd` is the operator's trusted hook, but branchKey
+            // is pipeline-derived and must not be able to inject (CodeQL
+            // js/shell-command-constructed-from-input).
+            const result = await exec('sh', ['-c', `${cmd} "$1"`, 'sh', branchKey]);
             stdout = result.stdout;
         }
         catch (err) {

package/dist/embedding/adapters/openai-text-embedding-3-small.d.ts

@@ -0,0 +1,71 @@
+/**
+ * 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 type { EmbeddingAdapter, EmbeddingAvailability, EmbeddingCapabilities, EmbeddingRequires } from '../types.js';
+import type { EmbeddingCostRecord } from '../types.js';
+/**
+ * Callback invoked by the adapter after each embed() / embedBatch() call
+ * with cost attribution data. The orchestrator wires this to CostTracker.
+ * Decoupled from CostTracker directly so the adapter can be unit-tested
+ * without a StateStore dependency.
+ */
+export type EmbeddingCostCallback = (record: EmbeddingCostRecord) => void;
+export declare class OpenAITextEmbedding3Small implements EmbeddingAdapter {
+    readonly name = "openai-text-embedding-3-small";
+    readonly modelId = "text-embedding-3-small";
+    readonly modelVersion = "2024-01-25";
+    readonly dimensions = 1536;
+    readonly capabilities: EmbeddingCapabilities;
+    readonly requires: EmbeddingRequires;
+    /** Optional cost-tracking callback. Set by the orchestrator after adapter instantiation. */
+    private costCallback?;
+    constructor(costCallback?: EmbeddingCostCallback);
+    /**
+     * Wire a cost-tracking callback after construction.
+     * Called by the orchestrator when it has a CostTracker available.
+     */
+    setCostCallback(callback: EmbeddingCostCallback): void;
+    isAvailable(): Promise<EmbeddingAvailability>;
+    getAccountId(): Promise<string | null>;
+    /**
+     * 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'.
+     */
+    embed(text: string, consumerLabel?: string): Promise<number[]>;
+    /**
+     * 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).
+     */
+    embedBatch(texts: string[], consumerLabel?: string): Promise<number[][]>;
+    /**
+     * Record a cost event via the cost callback.
+     * No-op when no callback is wired (e.g., in unit tests without a CostTracker).
+     */
+    private _recordCost;
+}
+//# sourceMappingURL=openai-text-embedding-3-small.d.ts.map

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