@legioncodeinc/nectar 0.0.1

package/dist/embeddings/config.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Embeddings-provider config resolution (PRD-014a).
+ *
+ * Resolves the ONE embeddings switch (DECISION #5) plus each provider's
+ * settings, with the daemon's precedence: explicit overrides -> environment ->
+ * built-in defaults (mirrors `src/config.ts` and `src/portkey/config.ts`). The
+ * selector is a three-value setting (`off | local | hosted`) that EXTENDS the
+ * vault `embeddings.enabled` boolean rather than sitting beside a parallel enable
+ * flag: a legacy truthy/falsey env value maps onto `local`/`off` so the switch is
+ * a genuine superset of the old boolean. Never throws at import time.
+ *
+ * Env names follow the `NECTAR_*` convention:
+ *   - `NECTAR_EMBEDDINGS_PROVIDER`          off | local | hosted (default local, AC-1)
+ *   - `NECTAR_EMBED_HOST` / `_PORT` / `_TIMEOUT_MS`   local nomic daemon transport
+ *   - `NECTAR_EMBEDDINGS_HOSTED_MODEL`      hosted embed model id (default text-embedding-3-small, decision #30 as amended)
+ *   - `NECTAR_EMBEDDINGS_OUTPUT_DIMENSION`  requested output dim (default 768, decision #30)
+ *   - `NECTAR_PORTKEY_API_KEY` / `_CONFIG`  the SAME gateway credentials the chat transport reads
+ */
+import { type HostedEmbeddingsConfig } from "./hosted-portkey.js";
+import { type LocalNomicConfig } from "./local-nomic.js";
+import { type EmbedProviderSelector } from "./provider.js";
+/** The fully-resolved embeddings config the switch (`resolveEmbedProvider`) consumes. */
+export interface ResolvedEmbeddingsConfig {
+    readonly selector: EmbedProviderSelector;
+    readonly local: LocalNomicConfig;
+    readonly hosted: HostedEmbeddingsConfig;
+}
+/** Explicit overrides for {@link resolveEmbeddingsConfig} (each wins over env + defaults). */
+export interface EmbeddingsConfigOverrides {
+    readonly selector?: EmbedProviderSelector;
+    readonly local?: Partial<LocalNomicConfig>;
+    readonly hosted?: Partial<HostedEmbeddingsConfig>;
+    /** Injectable env bag for tests; defaults to `process.env`. */
+    readonly env?: NodeJS.ProcessEnv;
+}
+/**
+ * Normalize a raw selector value into an {@link EmbedProviderSelector}, or
+ * `undefined` when it is unrecognized (so the caller falls back to the default).
+ * Accepts the three canonical values AND the legacy boolean vocabulary the vault
+ * `embeddings.enabled` key used (`true`/`1`/`on`/`yes` -> `local`,
+ * `false`/`0`/`off`/`no` -> `off`) so the selector is a superset of the boolean.
+ */
+export declare function normalizeSelector(raw: string | undefined): EmbedProviderSelector | undefined;
+/**
+ * Resolve the embeddings config. Overrides win, then env, then defaults. The
+ * selector defaults to `local` (AC-1 / DECISION #5); the hosted credentials
+ * resolve to `null` when Portkey is not keyed (the hosted provider then fails
+ * soft to nulls).
+ */
+export declare function resolveEmbeddingsConfig(overrides?: EmbeddingsConfigOverrides): ResolvedEmbeddingsConfig;
+/**
+ * The model id that produces embeddings under a resolved config, for stamping
+ * `embed_model` on persisted rows (PRD-018i / NEC-018 AC-018i.1):
+ *   - `off`    -> `null` (no embeddings are computed)
+ *   - `local`  -> the pinned {@link LOCAL_NOMIC_MODEL_ID}
+ *   - `hosted` -> the configured hosted model id
+ */
+export declare function activeEmbedModelId(config: ResolvedEmbeddingsConfig): string | null;
+/** The outcome of validating the requested hosted output dimension (PRD-018i / NEC-028 AC-018i.7). */
+export interface EmbedDimensionValidation {
+    readonly ok: boolean;
+    readonly requested: number;
+    readonly expected: number;
+    readonly message?: string;
+}
+/**
+ * Validate that a hosted output dimension matches the fixed {@link EMBED_DIMS}
+ * contract (PRD-018i / NEC-028 AC-018i.7). Any other value is pointless: the
+ * `FLOAT4[768]` column and the dim guard reject it, silently nulling every
+ * hosted vector. The caller warns loudly or refuses to start on `ok === false`.
+ * `off`/`local` selectors do not carry a requested dimension and always pass.
+ */
+export declare function validateEmbedDimension(config: ResolvedEmbeddingsConfig): EmbedDimensionValidation;
+//# sourceMappingURL=config.d.ts.map

package/dist/embeddings/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/embeddings/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAML,KAAK,sBAAsB,EAC5B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAKL,KAAK,gBAAgB,EACtB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAA0B,KAAK,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAEnF,yFAAyF;AACzF,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,QAAQ,EAAE,qBAAqB,CAAC;IACzC,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAC;CACzC;AAED,8FAA8F;AAC9F,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,QAAQ,CAAC,EAAE,qBAAqB,CAAC;IAC1C,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC3C,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,sBAAsB,CAAC,CAAC;IAClD,+DAA+D;IAC/D,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CAClC;AAeD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,qBAAqB,GAAG,SAAS,CAO5F;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,GAAE,yBAA8B,GAAG,wBAAwB,CA8B3G;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,wBAAwB,GAAG,MAAM,GAAG,IAAI,CAalF;AAED,sGAAsG;AACtG,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,wBAAwB,GAAG,wBAAwB,CAiBjG"}

package/dist/embeddings/config.js

@@ -0,0 +1,131 @@
+/**
+ * Embeddings-provider config resolution (PRD-014a).
+ *
+ * Resolves the ONE embeddings switch (DECISION #5) plus each provider's
+ * settings, with the daemon's precedence: explicit overrides -> environment ->
+ * built-in defaults (mirrors `src/config.ts` and `src/portkey/config.ts`). The
+ * selector is a three-value setting (`off | local | hosted`) that EXTENDS the
+ * vault `embeddings.enabled` boolean rather than sitting beside a parallel enable
+ * flag: a legacy truthy/falsey env value maps onto `local`/`off` so the switch is
+ * a genuine superset of the old boolean. Never throws at import time.
+ *
+ * Env names follow the `NECTAR_*` convention:
+ *   - `NECTAR_EMBEDDINGS_PROVIDER`          off | local | hosted (default local, AC-1)
+ *   - `NECTAR_EMBED_HOST` / `_PORT` / `_TIMEOUT_MS`   local nomic daemon transport
+ *   - `NECTAR_EMBEDDINGS_HOSTED_MODEL`      hosted embed model id (default text-embedding-3-small, decision #30 as amended)
+ *   - `NECTAR_EMBEDDINGS_OUTPUT_DIMENSION`  requested output dim (default 768, decision #30)
+ *   - `NECTAR_PORTKEY_API_KEY` / `_CONFIG`  the SAME gateway credentials the chat transport reads
+ */
+import { DEFAULT_HOSTED_EMBED_MODEL, DEFAULT_HOSTED_MAX_ATTEMPTS, DEFAULT_HOSTED_OUTPUT_DIMENSION, DEFAULT_HOSTED_REQUEST_TIMEOUT_MS, DEFAULT_HOSTED_RETRY_BACKOFF_MS, } from "./hosted-portkey.js";
+import { DEFAULT_LOCAL_EMBED_HOST, DEFAULT_LOCAL_EMBED_PORT, DEFAULT_LOCAL_EMBED_TIMEOUT_MS, LOCAL_NOMIC_MODEL_ID, } from "./local-nomic.js";
+import { PORTKEY_EMBEDDINGS_URL } from "../portkey/headers.js";
+import { EMBED_DIMS } from "../hive-graph/model.js";
+import { DEFAULT_EMBED_PROVIDER } from "./provider.js";
+function envStr(env, name) {
+    const raw = env[name];
+    if (raw === undefined || raw.trim() === "")
+        return undefined;
+    return raw;
+}
+function envInt(env, name) {
+    const raw = envStr(env, name);
+    if (raw === undefined)
+        return undefined;
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+/**
+ * Normalize a raw selector value into an {@link EmbedProviderSelector}, or
+ * `undefined` when it is unrecognized (so the caller falls back to the default).
+ * Accepts the three canonical values AND the legacy boolean vocabulary the vault
+ * `embeddings.enabled` key used (`true`/`1`/`on`/`yes` -> `local`,
+ * `false`/`0`/`off`/`no` -> `off`) so the selector is a superset of the boolean.
+ */
+export function normalizeSelector(raw) {
+    if (raw === undefined)
+        return undefined;
+    const v = raw.trim().toLowerCase();
+    if (v === "off" || v === "local" || v === "hosted")
+        return v;
+    if (v === "true" || v === "1" || v === "on" || v === "yes")
+        return "local";
+    if (v === "false" || v === "0" || v === "no")
+        return "off";
+    return undefined;
+}
+/**
+ * Resolve the embeddings config. Overrides win, then env, then defaults. The
+ * selector defaults to `local` (AC-1 / DECISION #5); the hosted credentials
+ * resolve to `null` when Portkey is not keyed (the hosted provider then fails
+ * soft to nulls).
+ */
+export function resolveEmbeddingsConfig(overrides = {}) {
+    const env = overrides.env ?? process.env;
+    const selector = overrides.selector ?? normalizeSelector(env.NECTAR_EMBEDDINGS_PROVIDER) ?? DEFAULT_EMBED_PROVIDER;
+    const local = {
+        host: overrides.local?.host ?? envStr(env, "NECTAR_EMBED_HOST") ?? DEFAULT_LOCAL_EMBED_HOST,
+        port: overrides.local?.port ?? envInt(env, "NECTAR_EMBED_PORT") ?? DEFAULT_LOCAL_EMBED_PORT,
+        requestTimeoutMs: overrides.local?.requestTimeoutMs ??
+            envInt(env, "NECTAR_EMBED_TIMEOUT_MS") ??
+            DEFAULT_LOCAL_EMBED_TIMEOUT_MS,
+    };
+    const hosted = {
+        model: overrides.hosted?.model ?? envStr(env, "NECTAR_EMBEDDINGS_HOSTED_MODEL") ?? DEFAULT_HOSTED_EMBED_MODEL,
+        outputDimension: overrides.hosted?.outputDimension ??
+            envInt(env, "NECTAR_EMBEDDINGS_OUTPUT_DIMENSION") ??
+            DEFAULT_HOSTED_OUTPUT_DIMENSION,
+        apiKey: overrides.hosted?.apiKey ?? envStr(env, "NECTAR_PORTKEY_API_KEY") ?? null,
+        configId: overrides.hosted?.configId ?? envStr(env, "NECTAR_PORTKEY_CONFIG") ?? null,
+        url: overrides.hosted?.url ?? PORTKEY_EMBEDDINGS_URL,
+        maxAttempts: overrides.hosted?.maxAttempts ?? DEFAULT_HOSTED_MAX_ATTEMPTS,
+        retryBackoffMs: overrides.hosted?.retryBackoffMs ?? DEFAULT_HOSTED_RETRY_BACKOFF_MS,
+        requestTimeoutMs: overrides.hosted?.requestTimeoutMs ?? DEFAULT_HOSTED_REQUEST_TIMEOUT_MS,
+    };
+    return { selector, local, hosted };
+}
+/**
+ * The model id that produces embeddings under a resolved config, for stamping
+ * `embed_model` on persisted rows (PRD-018i / NEC-018 AC-018i.1):
+ *   - `off`    -> `null` (no embeddings are computed)
+ *   - `local`  -> the pinned {@link LOCAL_NOMIC_MODEL_ID}
+ *   - `hosted` -> the configured hosted model id
+ */
+export function activeEmbedModelId(config) {
+    switch (config.selector) {
+        case "off":
+            return null;
+        case "local":
+            return LOCAL_NOMIC_MODEL_ID;
+        case "hosted":
+            return config.hosted.model;
+        default: {
+            const unreachable = config.selector;
+            return unreachable;
+        }
+    }
+}
+/**
+ * Validate that a hosted output dimension matches the fixed {@link EMBED_DIMS}
+ * contract (PRD-018i / NEC-028 AC-018i.7). Any other value is pointless: the
+ * `FLOAT4[768]` column and the dim guard reject it, silently nulling every
+ * hosted vector. The caller warns loudly or refuses to start on `ok === false`.
+ * `off`/`local` selectors do not carry a requested dimension and always pass.
+ */
+export function validateEmbedDimension(config) {
+    if (config.selector !== "hosted") {
+        return { ok: true, requested: EMBED_DIMS, expected: EMBED_DIMS };
+    }
+    const requested = config.hosted.outputDimension;
+    if (requested === EMBED_DIMS) {
+        return { ok: true, requested, expected: EMBED_DIMS };
+    }
+    return {
+        ok: false,
+        requested,
+        expected: EMBED_DIMS,
+        message: `NECTAR_EMBEDDINGS_OUTPUT_DIMENSION=${requested} does not match the fixed ${EMBED_DIMS}-dim ` +
+            `embedding contract (FLOAT4[${EMBED_DIMS}]); every hosted vector would be guard-discarded to null ` +
+            `and semantic recall would be permanently lexical-only. Set it to ${EMBED_DIMS} or unset it.`,
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/embeddings/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/embeddings/config.ts"],"names":[],"mappings":"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"}

package/dist/embeddings/guard.d.ts

@@ -0,0 +1,34 @@
+import type { EmbedProvider, EmbedProviderSelector } from "./provider.js";
+/** One discarded-vector event: which provider produced it, the contract dim, and the actual length. */
+export interface DimRejection {
+    /** The provider whose vector was discarded (`local` or `cohere`). */
+    readonly provider: EmbedProviderSelector;
+    /** The required dimension (always {@link EMBED_DIMS} = 768). */
+    readonly expected: number;
+    /** The actual length of the rejected vector. */
+    readonly actual: number;
+}
+/** The observability sink for a discarded wrong-dim vector (the `embed.dim_rejected` count/log seam). */
+export type DimRejectionSink = (rejection: DimRejection) => void;
+/**
+ * A body-free stderr sink an integrator can wire as the default observability for
+ * a discarded vector: it emits the dimension mismatch (never the vector itself)
+ * so an operator sees WHY recall degraded, mirroring honeycomb's "observable, not
+ * silently swallowed" posture. Never throws.
+ */
+export declare function stderrDimRejectionSink(rejection: DimRejection): void;
+/**
+ * Apply the dim guard to ONE vector: a `null` passes through, a 768-dim vector
+ * passes through, anything else is discarded to `null` and reported to `sink`.
+ * `sink` is invoked defensively — a faulty sink never breaks the embed path.
+ */
+export declare function guardVector(vec: number[] | null, provider: EmbedProviderSelector, sink?: DimRejectionSink): number[] | null;
+/**
+ * Wrap a computing provider so every returned vector passes the 768-dim guard
+ * (AC-3). The wrapper preserves the provider's `kind` and its 1:1 ordering; a
+ * wrong-dim vector at any position becomes `null` (reported to `sink`) while the
+ * rest pass through. The wrapped `embed` inherits the provider's never-throw
+ * contract.
+ */
+export declare function withDimGuard(provider: EmbedProvider, sink?: DimRejectionSink): EmbedProvider;
+//# sourceMappingURL=guard.d.ts.map

package/dist/embeddings/guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../../src/embeddings/guard.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAE1E,uGAAuG;AACvG,MAAM,WAAW,YAAY;IAC3B,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,EAAE,qBAAqB,CAAC;IACzC,gEAAgE;IAChE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,gDAAgD;IAChD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,yGAAyG;AACzG,MAAM,MAAM,gBAAgB,GAAG,CAAC,SAAS,EAAE,YAAY,KAAK,IAAI,CAAC;AAEjE;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,YAAY,GAAG,IAAI,CAIpE;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,EACpB,QAAQ,EAAE,qBAAqB,EAC/B,IAAI,CAAC,EAAE,gBAAgB,GACtB,MAAM,EAAE,GAAG,IAAI,CAYjB;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,aAAa,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,aAAa,CAQ5F"}

package/dist/embeddings/guard.js

@@ -0,0 +1,67 @@
+/**
+ * The 768-dim guard applied at the provider boundary (PRD-014 AC-3 / 014b
+ * US-014b.2 / 014c US-014c.3).
+ *
+ * The 768-dim contract is load-bearing: it ties to the `FLOAT4[768]` column and
+ * `EMBED_DIMS` (`hive-graph/model.ts`), matching `sessions.message_embedding`
+ * and `memory.summary_embedding` so the hybrid recall vector index sees one
+ * consistent dimensionality across every semantic arm
+ * (`ai/enricher-and-llm-model.md` § Embeddings). A vector of the wrong dimension
+ * from EITHER provider is discarded HERE — replaced with `null` so the caller
+ * leaves the column NULL and recall degrades to BM25, never stored as valid
+ * recall data. This is nectar's client-side mirror of honeycomb's
+ * `embed.dim_rejected` guard (`honeycomb .../embed-client.ts` returns `null` on
+ * `parsed.vector.length !== EMBEDDING_DIMS`).
+ *
+ * The rejection is reported through an injectable sink so the daemon can count /
+ * log it (the `embed.dim_rejected` semantics) without this module depending on a
+ * concrete telemetry surface. The default sink is a no-op — a wrong-dim vector
+ * still fails soft to `null` whether or not a sink is wired.
+ */
+import { EMBED_DIMS, isValidEmbedding } from "../hive-graph/model.js";
+/**
+ * A body-free stderr sink an integrator can wire as the default observability for
+ * a discarded vector: it emits the dimension mismatch (never the vector itself)
+ * so an operator sees WHY recall degraded, mirroring honeycomb's "observable, not
+ * silently swallowed" posture. Never throws.
+ */
+export function stderrDimRejectionSink(rejection) {
+    process.stderr.write(`nectar: embed.dim_rejected provider=${rejection.provider} expected=${rejection.expected} actual=${rejection.actual}\n`);
+}
+/**
+ * Apply the dim guard to ONE vector: a `null` passes through, a 768-dim vector
+ * passes through, anything else is discarded to `null` and reported to `sink`.
+ * `sink` is invoked defensively — a faulty sink never breaks the embed path.
+ */
+export function guardVector(vec, provider, sink) {
+    if (isValidEmbedding(vec))
+        return vec;
+    // `isValidEmbedding` only returns false for a non-null wrong-length vector, so `vec` is non-null here.
+    const actual = vec === null ? 0 : vec.length;
+    if (sink !== undefined) {
+        try {
+            sink({ provider, expected: EMBED_DIMS, actual });
+        }
+        catch {
+            // A rejection-sink fault is swallowed: observability is best-effort, never breaks the embed path.
+        }
+    }
+    return null;
+}
+/**
+ * Wrap a computing provider so every returned vector passes the 768-dim guard
+ * (AC-3). The wrapper preserves the provider's `kind` and its 1:1 ordering; a
+ * wrong-dim vector at any position becomes `null` (reported to `sink`) while the
+ * rest pass through. The wrapped `embed` inherits the provider's never-throw
+ * contract.
+ */
+export function withDimGuard(provider, sink) {
+    return {
+        kind: provider.kind,
+        async embed(texts) {
+            const raw = await provider.embed(texts);
+            return raw.map((vec) => guardVector(vec, provider.kind, sink));
+        },
+    };
+}
+//# sourceMappingURL=guard.js.map

package/dist/embeddings/guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard.js","sourceRoot":"","sources":["../../src/embeddings/guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAgBtE;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CAAC,SAAuB;IAC5D,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,uCAAuC,SAAS,CAAC,QAAQ,aAAa,SAAS,CAAC,QAAQ,WAAW,SAAS,CAAC,MAAM,IAAI,CACxH,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CACzB,GAAoB,EACpB,QAA+B,EAC/B,IAAuB;IAEvB,IAAI,gBAAgB,CAAC,GAAG,CAAC;QAAE,OAAO,GAAG,CAAC;IACtC,uGAAuG;IACvG,MAAM,MAAM,GAAG,GAAG,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC;IAC7C,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,IAAI,CAAC;YACH,IAAI,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC;QACnD,CAAC;QAAC,MAAM,CAAC;YACP,kGAAkG;QACpG,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,QAAuB,EAAE,IAAuB;IAC3E,OAAO;QACL,IAAI,EAAE,QAAQ,CAAC,IAAI;QACnB,KAAK,CAAC,KAAK,CAAC,KAAwB;YAClC,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YACxC,OAAO,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,WAAW,CAAC,GAAG,EAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;QACjE,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/embeddings/hosted-portkey.d.ts

@@ -0,0 +1,73 @@
+import { type FetchLike, type SleepFn } from "./http.js";
+import type { EmbedProvider } from "./provider.js";
+/**
+ * SIGNED OFF 2026-07-02 (decision #30 AS AMENDED, PM): the hosted embed model
+ * the opt-in targets. OpenAI `text-embedding-3-small` natively supports a 768
+ * `dimensions` request, so the opt-in produces contract-valid vectors with no
+ * client-side math. (The original #30 pick, Cohere embed-v4.0, accepts only
+ * [256, 512, 1024, 1536] and was amended away; it stays reachable by config
+ * for an operator whose gateway maps dimensions, with the guard as backstop.)
+ * Config-overridable.
+ */
+export declare const DEFAULT_HOSTED_EMBED_MODEL: "text-embedding-3-small";
+/**
+ * SIGNED OFF 2026-07-02 (decision #30 as amended): the requested output
+ * dimension. 768 keeps the opt-in on the fixed 768-dim contract; the guard
+ * discards anything else. Config-overridable.
+ */
+export declare const DEFAULT_HOSTED_OUTPUT_DIMENSION: 768;
+/** HTTP statuses that trigger a bounded retry (429 rate limit + transient 5xx), matching the chat transport. */
+export declare const HOSTED_RETRYABLE_STATUSES: ReadonlySet<number>;
+/** Maximum attempts including the first POST (mirrors `src/portkey/transport.ts`'s `PORTKEY_MAX_ATTEMPTS`). */
+export declare const DEFAULT_HOSTED_MAX_ATTEMPTS: 3;
+/** Backoff between retryable failures in ms (mirrors `src/portkey/transport.ts`'s backoff). */
+export declare const DEFAULT_HOSTED_RETRY_BACKOFF_MS: 250;
+/**
+ * Per-attempt request timeout (ms), mirroring `deeplake-transport.ts`'s
+ * `DEFAULT_TRANSPORT_TIMEOUT_MS` AbortController pattern: an unresponsive gateway
+ * aborts rather than hanging the embed path indefinitely (fail-soft, AC-4).
+ */
+export declare const DEFAULT_HOSTED_REQUEST_TIMEOUT_MS: 15000;
+/** The resolved hosted-via-Portkey config. `apiKey`/`configId` are `null` when Portkey is not keyed. */
+export interface HostedEmbeddingsConfig {
+    /** The hosted embed model id (default {@link DEFAULT_HOSTED_EMBED_MODEL}). Config-overridable (AC-2). */
+    readonly model: string;
+    /** The requested output dimension (default {@link DEFAULT_HOSTED_OUTPUT_DIMENSION}). Config-overridable (AC-2). */
+    readonly outputDimension: number;
+    /** The resolved Portkey API key, or `null` when unkeyed (then embed fails soft to nulls). */
+    readonly apiKey: string | null;
+    /** The `portkey.config` / virtual-key id, or `null` when unset. */
+    readonly configId: string | null;
+    /** The endpoint URL (default {@link PORTKEY_EMBEDDINGS_URL}); overridable for a fake-fetch test. */
+    readonly url: string;
+    /** Max attempts including the first POST. */
+    readonly maxAttempts: number;
+    /** Backoff between retryable failures (ms). */
+    readonly retryBackoffMs: number;
+    /** Per-attempt request timeout (ms) before the attempt aborts (default {@link DEFAULT_HOSTED_REQUEST_TIMEOUT_MS}). */
+    readonly requestTimeoutMs: number;
+}
+/** Construction deps for {@link createHostedPortkeyProvider}; fetch + sleep are injectable for tests. */
+export interface HostedPortkeyDeps {
+    /** The `fetch` implementation; defaults to `globalThis.fetch`. Tests inject a fake (no network). */
+    readonly fetch?: FetchLike;
+    /** The backoff sleep; a test passes a no-op so retry paths run without real time. */
+    readonly sleep?: SleepFn;
+}
+/**
+ * Parse the embeddings response into one vector (or `null`) per input index,
+ * defensively. Primary shape is Portkey's OpenAI-compatible
+ * `{ data: [{ embedding: number[], index }] }`; a Cohere-native
+ * `{ embeddings: number[][] }` or `{ embeddings: { float: number[][] } }` body is
+ * tolerated as a fallback. Anything else yields all-nulls. Never throws. The
+ * per-vector dimension is NOT checked here — the guard owns that (AC-3).
+ */
+export declare function parseEmbeddingsResponse(raw: string, count: number): (number[] | null)[];
+/**
+ * Build the hosted-via-Portkey embeddings {@link EmbedProvider} (PRD-014b). A
+ * batch is sent as ONE POST reusing the rerank transport's auth pattern; the body
+ * carries the config model id + `dimensions` (AC-2). Every failure resolves
+ * to nulls for the batch (fail-soft, AC-4); the key is never logged or thrown.
+ */
+export declare function createHostedPortkeyProvider(config: HostedEmbeddingsConfig, deps?: HostedPortkeyDeps): EmbedProvider;
+//# sourceMappingURL=hosted-portkey.d.ts.map

package/dist/embeddings/hosted-portkey.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hosted-portkey.d.ts","sourceRoot":"","sources":["../../src/embeddings/hosted-portkey.ts"],"names":[],"mappings":"AA+BA,OAAO,EAA8B,KAAK,SAAS,EAAE,KAAK,OAAO,EAAE,MAAM,WAAW,CAAC;AACrF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEnD;;;;;;;;GAQG;AACH,eAAO,MAAM,0BAA0B,EAAG,wBAAiC,CAAC;AAE5E;;;;GAIG;AACH,eAAO,MAAM,+BAA+B,EAAG,GAAY,CAAC;AAE5D,gHAAgH;AAChH,eAAO,MAAM,yBAAyB,EAAE,WAAW,CAAC,MAAM,CAAsC,CAAC;AAEjG,+GAA+G;AAC/G,eAAO,MAAM,2BAA2B,EAAG,CAAU,CAAC;AAEtD,+FAA+F;AAC/F,eAAO,MAAM,+BAA+B,EAAG,GAAY,CAAC;AAE5D;;;;GAIG;AACH,eAAO,MAAM,iCAAiC,EAAG,KAAe,CAAC;AAEjE,wGAAwG;AACxG,MAAM,WAAW,sBAAsB;IACrC,yGAAyG;IACzG,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,mHAAmH;IACnH,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,6FAA6F;IAC7F,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,oGAAoG;IACpG,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,6CAA6C;IAC7C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,+CAA+C;IAC/C,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,sHAAsH;IACtH,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;CACnC;AAED,yGAAyG;AACzG,MAAM,WAAW,iBAAiB;IAChC,oGAAoG;IACpG,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC;IAC3B,qFAAqF;IACrF,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAOD;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,EAAE,CAyCvF;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,sBAAsB,EAC9B,IAAI,GAAE,iBAAsB,GAC3B,aAAa,CAwDf"}

package/dist/embeddings/hosted-portkey.js

@@ -0,0 +1,179 @@
+/**
+ * The hosted-via-Portkey embeddings transport (PRD-014b — the operator opt-in).
+ *
+ * Modeled on honeycomb's shipped Cohere-rerank-via-Portkey transport
+ * (`honeycomb/src/daemon/runtime/recall/rerank-portkey.ts`): it reuses the SAME
+ * `x-portkey-api-key` + `x-portkey-config` auth pair (via
+ * {@link buildPortkeyHeaders}) and the SAME gateway host; the ONE difference is
+ * the path — `/v1/embeddings` ({@link PORTKEY_EMBEDDINGS_URL}) instead of
+ * `/v1/rerank` — and the request/response shape.
+ *
+ * ── Model + dimension are config, not hardcoded (decision #30 as amended) ────
+ * The opt-in targets OpenAI `text-embedding-3-small` with `dimensions: 768` so
+ * it produces contract-valid 768-dim vectors with no client-side math. Both the
+ * model id and the dimension are config values
+ * ({@link HostedEmbeddingsConfig}); recall's 768-dim guard (`guard.ts`) stays as
+ * the backstop for whatever the gateway actually returns.
+ *
+ * ── Fail-soft is the cardinal rule (AC-4 / US-014b.3) ────────────────────────
+ * EVERY failure path — Portkey not keyed, a network/transport error, a non-2xx
+ * gateway status, or a malformed body — resolves to `null` for the affected
+ * texts, NEVER a throw into the caller's hot path. A bounded retry covers 429 +
+ * transient 5xx (the same statuses the sibling chat transport retries); the
+ * bound is exhausted to nulls rather than thrown.
+ *
+ * ── The secret-never-logged invariant (US-014b.3) ────────────────────────────
+ * The resolved key is placed ONLY in the `x-portkey-api-key` header (via
+ * {@link buildPortkeyHeaders}) and is NEVER included in a returned value, a log
+ * line, or an error. On any failure the response body is not read into a message
+ * (it could echo a credential).
+ */
+import { buildPortkeyHeaders, PORTKEY_EMBEDDINGS_URL } from "../portkey/headers.js";
+import { defaultFetch, defaultSleep } from "./http.js";
+/**
+ * SIGNED OFF 2026-07-02 (decision #30 AS AMENDED, PM): the hosted embed model
+ * the opt-in targets. OpenAI `text-embedding-3-small` natively supports a 768
+ * `dimensions` request, so the opt-in produces contract-valid vectors with no
+ * client-side math. (The original #30 pick, Cohere embed-v4.0, accepts only
+ * [256, 512, 1024, 1536] and was amended away; it stays reachable by config
+ * for an operator whose gateway maps dimensions, with the guard as backstop.)
+ * Config-overridable.
+ */
+export const DEFAULT_HOSTED_EMBED_MODEL = "text-embedding-3-small";
+/**
+ * SIGNED OFF 2026-07-02 (decision #30 as amended): the requested output
+ * dimension. 768 keeps the opt-in on the fixed 768-dim contract; the guard
+ * discards anything else. Config-overridable.
+ */
+export const DEFAULT_HOSTED_OUTPUT_DIMENSION = 768;
+/** HTTP statuses that trigger a bounded retry (429 rate limit + transient 5xx), matching the chat transport. */
+export const HOSTED_RETRYABLE_STATUSES = new Set([429, 500, 502, 503, 504]);
+/** Maximum attempts including the first POST (mirrors `src/portkey/transport.ts`'s `PORTKEY_MAX_ATTEMPTS`). */
+export const DEFAULT_HOSTED_MAX_ATTEMPTS = 3;
+/** Backoff between retryable failures in ms (mirrors `src/portkey/transport.ts`'s backoff). */
+export const DEFAULT_HOSTED_RETRY_BACKOFF_MS = 250;
+/**
+ * Per-attempt request timeout (ms), mirroring `deeplake-transport.ts`'s
+ * `DEFAULT_TRANSPORT_TIMEOUT_MS` AbortController pattern: an unresponsive gateway
+ * aborts rather than hanging the embed path indefinitely (fail-soft, AC-4).
+ */
+export const DEFAULT_HOSTED_REQUEST_TIMEOUT_MS = 15_000;
+/** All-nulls result of length `n` (the fail-soft shape, built in one place). */
+function allNull(n) {
+    return new Array(n).fill(null);
+}
+/**
+ * Parse the embeddings response into one vector (or `null`) per input index,
+ * defensively. Primary shape is Portkey's OpenAI-compatible
+ * `{ data: [{ embedding: number[], index }] }`; a Cohere-native
+ * `{ embeddings: number[][] }` or `{ embeddings: { float: number[][] } }` body is
+ * tolerated as a fallback. Anything else yields all-nulls. Never throws. The
+ * per-vector dimension is NOT checked here — the guard owns that (AC-3).
+ */
+export function parseEmbeddingsResponse(raw, count) {
+    let body;
+    try {
+        body = raw.length > 0 ? JSON.parse(raw) : null;
+    }
+    catch {
+        return allNull(count);
+    }
+    if (typeof body !== "object" || body === null)
+        return allNull(count);
+    const out = allNull(count);
+    const asFinite = (v) => Array.isArray(v) && v.every((n) => typeof n === "number" && Number.isFinite(n)) ? v : null;
+    // Primary: OpenAI-compatible `data: [{ embedding, index }]`.
+    const data = body.data;
+    if (Array.isArray(data)) {
+        data.forEach((entry, i) => {
+            if (typeof entry !== "object" || entry === null)
+                return;
+            const e = entry;
+            const idx = typeof e.index === "number" && Number.isInteger(e.index) ? e.index : i;
+            if (idx < 0 || idx >= count)
+                return;
+            out[idx] = asFinite(e.embedding);
+        });
+        return out;
+    }
+    // Fallback: Cohere-native `embeddings: number[][]` or `embeddings: { float: number[][] }`.
+    const embeddings = body.embeddings;
+    const rows = Array.isArray(embeddings)
+        ? embeddings
+        : typeof embeddings === "object" && embeddings !== null && Array.isArray(embeddings.float)
+            ? (embeddings.float)
+            : null;
+    if (rows !== null) {
+        rows.forEach((row, i) => {
+            if (i < count)
+                out[i] = asFinite(row);
+        });
+        return out;
+    }
+    return allNull(count);
+}
+/**
+ * Build the hosted-via-Portkey embeddings {@link EmbedProvider} (PRD-014b). A
+ * batch is sent as ONE POST reusing the rerank transport's auth pattern; the body
+ * carries the config model id + `dimensions` (AC-2). Every failure resolves
+ * to nulls for the batch (fail-soft, AC-4); the key is never logged or thrown.
+ */
+export function createHostedPortkeyProvider(config, deps = {}) {
+    const doFetch = deps.fetch ?? defaultFetch();
+    const sleep = deps.sleep ?? defaultSleep;
+    return {
+        kind: "hosted",
+        async embed(texts) {
+            if (texts.length === 0)
+                return [];
+            // Not keyed -> fail soft to nulls (no POST). A missing key is a misconfiguration, not a crash (AC-4).
+            if (config.apiKey === null || config.configId === null)
+                return allNull(texts.length);
+            const headers = buildPortkeyHeaders(config.apiKey, config.configId);
+            // The embeddings body (decision #30 as amended): the config model id + the
+            // OpenAI-compatible `dimensions` field (Portkey's unified API maps it to the
+            // provider's own parameter, e.g. Cohere's `output_dimension`), both overridable (AC-2).
+            const body = JSON.stringify({
+                model: config.model,
+                input: [...texts],
+                dimensions: config.outputDimension,
+            });
+            for (let attempt = 1; attempt <= config.maxAttempts; attempt++) {
+                let res;
+                const controller = new AbortController();
+                const timer = setTimeout(() => controller.abort(), config.requestTimeoutMs);
+                try {
+                    res = await doFetch(config.url, { method: "POST", headers, body, signal: controller.signal });
+                }
+                catch {
+                    // Network/transport failure, or our own abort on `requestTimeoutMs` (an unresponsive
+                    // gateway) -> retry within the bound, else fail soft to nulls. Never surface the error
+                    // (it could carry a body/key); only the fail-soft nulls escape.
+                    if (attempt < config.maxAttempts) {
+                        await sleep(config.retryBackoffMs * attempt);
+                        continue;
+                    }
+                    return allNull(texts.length);
+                }
+                finally {
+                    clearTimeout(timer);
+                }
+                if (!res.ok) {
+                    // A non-2xx gateway status: retry the retryable ones within the bound, else fail soft. Never
+                    // read the body into a message (it could echo a credential).
+                    if (attempt < config.maxAttempts && HOSTED_RETRYABLE_STATUSES.has(res.status)) {
+                        await sleep(config.retryBackoffMs * attempt);
+                        continue;
+                    }
+                    return allNull(texts.length);
+                }
+                // A 2xx: parse defensively. A malformed body fails soft to nulls (the gateway was reachable,
+                // the body was just unusable) rather than throwing.
+                const text = await res.text().catch(() => "");
+                return parseEmbeddingsResponse(text, texts.length);
+            }
+            return allNull(texts.length);
+        },
+    };
+}
+//# sourceMappingURL=hosted-portkey.js.map

package/dist/embeddings/hosted-portkey.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hosted-portkey.js","sourceRoot":"","sources":["../../src/embeddings/hosted-portkey.ts"],"names":[],"mappings":"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"}

package/dist/embeddings/http.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The injectable HTTP seam shared by both embedding transports (PRD-014).
+ *
+ * A minimal `fetch`-shaped surface so neither the local nomic client nor the
+ * hosted-via-Portkey transport touches the network in a unit test: production
+ * binds `globalThis.fetch`, a test injects a fake that returns a canned
+ * response. The shape is deliberately identical to the sibling chat transport's
+ * `PortkeyFetch` (`src/portkey/transport.ts`) so the Wave-2 integrator can fold
+ * the two onto one shared seam without a signature change.
+ */
+/** The subset of a `fetch` `Response` the transports read. */
+export interface FetchResponseLike {
+    /** True on a 2xx status. */
+    readonly ok: boolean;
+    /** The HTTP status code (routed to the bounded-retry decision + the fail-soft path). */
+    readonly status: number;
+    /** The raw response body; parsed defensively by the caller (never trusted). */
+    text(): Promise<string>;
+}
+/** The injectable `fetch` implementation. Production: `globalThis.fetch`; tests inject a fake. */
+export type FetchLike = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+    signal?: AbortSignal;
+}) => Promise<FetchResponseLike>;
+/** Bind the real global `fetch` to the {@link FetchLike} shape (Node >=22 ships it as a built-in). */
+export declare function defaultFetch(): FetchLike;
+/** An injectable backoff sleep; tests pass a no-op so retry paths run without real time. */
+export type SleepFn = (ms: number) => Promise<void>;
+/** The production sleep, backed by a real timer. */
+export declare function defaultSleep(ms: number): Promise<void>;
+//# sourceMappingURL=http.d.ts.map

package/dist/embeddings/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/embeddings/http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,8DAA8D;AAC9D,MAAM,WAAW,iBAAiB;IAChC,4BAA4B;IAC5B,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,wFAAwF;IACxF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,+EAA+E;IAC/E,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CACzB;AAED,kGAAkG;AAClG,MAAM,MAAM,SAAS,GAAG,CACtB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,KAC1F,OAAO,CAAC,iBAAiB,CAAC,CAAC;AAEhC,sGAAsG;AACtG,wBAAgB,YAAY,IAAI,SAAS,CAExC;AAED,4FAA4F;AAC5F,MAAM,MAAM,OAAO,GAAG,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAEpD,oDAAoD;AACpD,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEtD"}