@legioncodeinc/nectar 0.0.1

package/dist/portkey/describe-model.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The `describe_model` audit seam (PRD-010b).
+ *
+ * Stamps which model produced a description on a `hive_graph_versions` row and
+ * computes which rows `brood --force --model <new>` must reset to `pending` before
+ * re-description (AC-3). The CLI verb itself is owned by PRD-007; this module is
+ * the pure field logic the integrator wires.
+ */
+import type { DescribeStatus, HiveGraphVersionRow } from "../hive-graph/model.js";
+/** The three skip statuses that `--force` must not reset (AC-3). */
+export declare const SKIPPED_DESCRIBE_STATUSES: readonly DescribeStatus[];
+/** True when a row's describe status is one of the brooding skip outcomes. */
+export declare function isSkippedDescribeStatus(status: DescribeStatus): boolean;
+/** Structured description payload returned by the Portkey call (brooding/enricher). */
+export interface DescriptionPayload {
+    readonly title: string;
+    readonly description: string;
+    readonly concepts: string;
+}
+/** Field patch applied when a row transitions to `describe_status = 'described'`. */
+export interface DescribeModelStamp {
+    readonly title: string;
+    readonly description: string;
+    readonly concepts: string;
+    readonly describeModel: string;
+    readonly describeStatus: "described";
+    readonly describedAt: string;
+}
+/**
+ * Build the audit-stamping patch for a freshly described row (AC-4).
+ * `modelId` is the resolved target model for the run (explicit override or activeModel).
+ */
+export declare function buildDescribeModelStamp(payload: DescriptionPayload, modelId: string, describedAt: string): DescribeModelStamp;
+/** Minimal row shape {@link resetForRedescribe} needs. */
+export interface RedescribeRow {
+    readonly nectar: string;
+    readonly contentHash: string;
+    readonly describeStatus: DescribeStatus;
+}
+/** One row reset by `brood --force --model <new>`. */
+export interface RedescribeReset {
+    readonly nectar: string;
+    readonly contentHash: string;
+    readonly describeStatus: "pending";
+}
+/**
+ * Given version rows, return the subset that `--force` resets to `pending` (AC-3):
+ * every non-skipped row, regardless of prior `described` / `failed` / `pending` state.
+ */
+export declare function resetForRedescribe(rows: readonly RedescribeRow[]): RedescribeReset[];
+/** Apply a describe stamp onto a full version row (immutable return for tests/adapters). */
+export declare function applyDescribeModelStamp(row: HiveGraphVersionRow, stamp: DescribeModelStamp): HiveGraphVersionRow;
+//# sourceMappingURL=describe-model.d.ts.map

package/dist/portkey/describe-model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe-model.d.ts","sourceRoot":"","sources":["../../src/portkey/describe-model.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAElF,oEAAoE;AACpE,eAAO,MAAM,yBAAyB,EAAE,SAAS,cAAc,EAI9D,CAAC;AAEF,8EAA8E;AAC9E,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAMvE;AAED,uFAAuF;AACvF,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,qFAAqF;AACrF,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,cAAc,EAAE,WAAW,CAAC;IACrC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,kBAAkB,EAC3B,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,GAClB,kBAAkB,CASpB;AAED,0DAA0D;AAC1D,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;CACzC;AAED,sDAAsD;AACtD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE,SAAS,CAAC;CACpC;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,SAAS,aAAa,EAAE,GAAG,eAAe,EAAE,CAWpF;AAED,4FAA4F;AAC5F,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,mBAAmB,EACxB,KAAK,EAAE,kBAAkB,GACxB,mBAAmB,CAUrB"}

package/dist/portkey/describe-model.js

@@ -0,0 +1,56 @@
+/** The three skip statuses that `--force` must not reset (AC-3). */
+export const SKIPPED_DESCRIBE_STATUSES = [
+    "skipped-too-large",
+    "skipped-binary",
+    "skipped-deleted",
+];
+/** True when a row's describe status is one of the brooding skip outcomes. */
+export function isSkippedDescribeStatus(status) {
+    return (status === "skipped-too-large" ||
+        status === "skipped-binary" ||
+        status === "skipped-deleted");
+}
+/**
+ * Build the audit-stamping patch for a freshly described row (AC-4).
+ * `modelId` is the resolved target model for the run (explicit override or activeModel).
+ */
+export function buildDescribeModelStamp(payload, modelId, describedAt) {
+    return {
+        title: payload.title,
+        description: payload.description,
+        concepts: payload.concepts,
+        describeModel: modelId,
+        describeStatus: "described",
+        describedAt,
+    };
+}
+/**
+ * Given version rows, return the subset that `--force` resets to `pending` (AC-3):
+ * every non-skipped row, regardless of prior `described` / `failed` / `pending` state.
+ */
+export function resetForRedescribe(rows) {
+    const resets = [];
+    for (const row of rows) {
+        if (isSkippedDescribeStatus(row.describeStatus))
+            continue;
+        resets.push({
+            nectar: row.nectar,
+            contentHash: row.contentHash,
+            describeStatus: "pending",
+        });
+    }
+    return resets;
+}
+/** Apply a describe stamp onto a full version row (immutable return for tests/adapters). */
+export function applyDescribeModelStamp(row, stamp) {
+    return {
+        ...row,
+        title: stamp.title,
+        description: stamp.description,
+        concepts: stamp.concepts,
+        describeModel: stamp.describeModel,
+        describeStatus: stamp.describeStatus,
+        describedAt: stamp.describedAt,
+    };
+}
+//# sourceMappingURL=describe-model.js.map

package/dist/portkey/describe-model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe-model.js","sourceRoot":"","sources":["../../src/portkey/describe-model.ts"],"names":[],"mappings":"AAUA,oEAAoE;AACpE,MAAM,CAAC,MAAM,yBAAyB,GAA8B;IAClE,mBAAmB;IACnB,gBAAgB;IAChB,iBAAiB;CAClB,CAAC;AAEF,8EAA8E;AAC9E,MAAM,UAAU,uBAAuB,CAAC,MAAsB;IAC5D,OAAO,CACL,MAAM,KAAK,mBAAmB;QAC9B,MAAM,KAAK,gBAAgB;QAC3B,MAAM,KAAK,iBAAiB,CAC7B,CAAC;AACJ,CAAC;AAmBD;;;GAGG;AACH,MAAM,UAAU,uBAAuB,CACrC,OAA2B,EAC3B,OAAe,EACf,WAAmB;IAEnB,OAAO;QACL,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,aAAa,EAAE,OAAO;QACtB,cAAc,EAAE,WAAW;QAC3B,WAAW;KACZ,CAAC;AACJ,CAAC;AAgBD;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAA8B;IAC/D,MAAM,MAAM,GAAsB,EAAE,CAAC;IACrC,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,IAAI,uBAAuB,CAAC,GAAG,CAAC,cAAc,CAAC;YAAE,SAAS;QAC1D,MAAM,CAAC,IAAI,CAAC;YACV,MAAM,EAAE,GAAG,CAAC,MAAM;YAClB,WAAW,EAAE,GAAG,CAAC,WAAW;YAC5B,cAAc,EAAE,SAAS;SAC1B,CAAC,CAAC;IACL,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,4FAA4F;AAC5F,MAAM,UAAU,uBAAuB,CACrC,GAAwB,EACxB,KAAyB;IAEzB,OAAO;QACL,GAAG,GAAG;QACN,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,aAAa,EAAE,KAAK,CAAC,aAAa;QAClC,cAAc,EAAE,KAAK,CAAC,cAAc;QACpC,WAAW,EAAE,KAAK,CAAC,WAAW;KAC/B,CAAC;AACJ,CAAC"}

package/dist/portkey/headers.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Portkey gateway request headers and endpoint constants (PRD-010a).
+ *
+ * Mirrors honeycomb's shared header builder and base URL so nectar reaches
+ * the same gateway wire shape without importing honeycomb in-process (ADR-0002).
+ * Canonical reference: `honeycomb/src/daemon/runtime/inference/transport-portkey.ts`
+ * (`PORTKEY_BASE_URL`, `PORTKEY_CHAT_COMPLETIONS_URL`, `buildPortkeyHeaders`).
+ */
+/** The Portkey gateway base host. Confirmed vs Portkey docs at honeycomb build time. */
+export declare const PORTKEY_BASE_URL: "https://api.portkey.ai/v1";
+/** The Portkey OpenAI-compatible chat-completions endpoint. */
+export declare const PORTKEY_CHAT_COMPLETIONS_URL: "https://api.portkey.ai/v1/chat/completions";
+/**
+ * The Portkey OpenAI-compatible embeddings endpoint (decision #30 / PRD-014b).
+ * The chat, rerank, and embeddings transports all hang off {@link PORTKEY_BASE_URL};
+ * the ONE difference from the chat path is `/embeddings` vs `/chat/completions`.
+ * The Cohere-via-Portkey embed transport (`src/embeddings/cohere-portkey.ts`)
+ * posts here. Confirm the live gateway still advertises this path before first
+ * opt-in use (the decision doc flags it as a mechanical check).
+ */
+export declare const PORTKEY_EMBEDDINGS_URL: "https://api.portkey.ai/v1/embeddings";
+/** Header carrying the resolved Portkey API key (never logged or echoed). */
+export declare const PORTKEY_API_KEY_HEADER: "x-portkey-api-key";
+/** Header carrying the `portkey.config` / virtual-key id (non-secret). */
+export declare const PORTKEY_CONFIG_HEADER: "x-portkey-config";
+/**
+ * Build the Portkey request headers shared by chat and future rerank/embed transports.
+ * `apiKey` is placed ONLY in the auth header; `configId` is the non-secret config id.
+ */
+export declare function buildPortkeyHeaders(apiKey: string, configId: string): Record<string, string>;
+//# sourceMappingURL=headers.d.ts.map

package/dist/portkey/headers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"headers.d.ts","sourceRoot":"","sources":["../../src/portkey/headers.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,wFAAwF;AACxF,eAAO,MAAM,gBAAgB,EAAG,2BAAoC,CAAC;AAErE,+DAA+D;AAC/D,eAAO,MAAM,4BAA4B,8CAAkD,CAAC;AAE5F;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,wCAA4C,CAAC;AAEhF,6EAA6E;AAC7E,eAAO,MAAM,sBAAsB,EAAG,mBAA4B,CAAC;AAEnE,0EAA0E;AAC1E,eAAO,MAAM,qBAAqB,EAAG,kBAA2B,CAAC;AAEjE;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAM5F"}

package/dist/portkey/headers.js

@@ -0,0 +1,37 @@
+/**
+ * Portkey gateway request headers and endpoint constants (PRD-010a).
+ *
+ * Mirrors honeycomb's shared header builder and base URL so nectar reaches
+ * the same gateway wire shape without importing honeycomb in-process (ADR-0002).
+ * Canonical reference: `honeycomb/src/daemon/runtime/inference/transport-portkey.ts`
+ * (`PORTKEY_BASE_URL`, `PORTKEY_CHAT_COMPLETIONS_URL`, `buildPortkeyHeaders`).
+ */
+/** The Portkey gateway base host. Confirmed vs Portkey docs at honeycomb build time. */
+export const PORTKEY_BASE_URL = "https://api.portkey.ai/v1";
+/** The Portkey OpenAI-compatible chat-completions endpoint. */
+export const PORTKEY_CHAT_COMPLETIONS_URL = `${PORTKEY_BASE_URL}/chat/completions`;
+/**
+ * The Portkey OpenAI-compatible embeddings endpoint (decision #30 / PRD-014b).
+ * The chat, rerank, and embeddings transports all hang off {@link PORTKEY_BASE_URL};
+ * the ONE difference from the chat path is `/embeddings` vs `/chat/completions`.
+ * The Cohere-via-Portkey embed transport (`src/embeddings/cohere-portkey.ts`)
+ * posts here. Confirm the live gateway still advertises this path before first
+ * opt-in use (the decision doc flags it as a mechanical check).
+ */
+export const PORTKEY_EMBEDDINGS_URL = `${PORTKEY_BASE_URL}/embeddings`;
+/** Header carrying the resolved Portkey API key (never logged or echoed). */
+export const PORTKEY_API_KEY_HEADER = "x-portkey-api-key";
+/** Header carrying the `portkey.config` / virtual-key id (non-secret). */
+export const PORTKEY_CONFIG_HEADER = "x-portkey-config";
+/**
+ * Build the Portkey request headers shared by chat and future rerank/embed transports.
+ * `apiKey` is placed ONLY in the auth header; `configId` is the non-secret config id.
+ */
+export function buildPortkeyHeaders(apiKey, configId) {
+    return {
+        [PORTKEY_API_KEY_HEADER]: apiKey,
+        [PORTKEY_CONFIG_HEADER]: configId,
+        "content-type": "application/json",
+    };
+}
+//# sourceMappingURL=headers.js.map

package/dist/portkey/headers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"headers.js","sourceRoot":"","sources":["../../src/portkey/headers.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,wFAAwF;AACxF,MAAM,CAAC,MAAM,gBAAgB,GAAG,2BAAoC,CAAC;AAErE,+DAA+D;AAC/D,MAAM,CAAC,MAAM,4BAA4B,GAAG,GAAG,gBAAgB,mBAA4B,CAAC;AAE5F;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,GAAG,gBAAgB,aAAsB,CAAC;AAEhF,6EAA6E;AAC7E,MAAM,CAAC,MAAM,sBAAsB,GAAG,mBAA4B,CAAC;AAEnE,0EAA0E;AAC1E,MAAM,CAAC,MAAM,qBAAqB,GAAG,kBAA2B,CAAC;AAEjE;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAAc,EAAE,QAAgB;IAClE,OAAO;QACL,CAAC,sBAAsB,CAAC,EAAE,MAAM;QAChC,CAAC,qBAAqB,CAAC,EAAE,QAAQ;QACjC,cAAc,EAAE,kBAAkB;KACnC,CAAC;AACJ,CAAC"}

package/dist/portkey/transport.d.ts

@@ -0,0 +1,89 @@
+import { type PortkeyEnabled } from "./config.js";
+/** Sane completion ceiling when the caller omits `maxTokens`. */
+export declare const PORTKEY_DEFAULT_MAX_TOKENS: 4096;
+/** HTTP statuses that trigger a bounded retry (429 rate limit + transient 5xx). */
+export declare const PORTKEY_RETRYABLE_STATUSES: Set<number>;
+/** Maximum attempts including the first POST (DEFAULT - confirm before implementation). */
+export declare const PORTKEY_MAX_ATTEMPTS: 3;
+/** Backoff between retryable failures in ms (DEFAULT - confirm before implementation). */
+export declare const PORTKEY_RETRY_BACKOFF_MS: 250;
+/**
+ * Per-attempt request timeout (ms), mirroring `hive-graph/deeplake-transport.ts`'s
+ * `DEFAULT_TRANSPORT_TIMEOUT_MS` AbortController pattern: an unresponsive gateway
+ * aborts rather than hanging the caller indefinitely. Solo describe calls use
+ * this default; batch calls request the raised {@link PORTKEY_BATCH_REQUEST_TIMEOUT_MS}.
+ */
+export declare const PORTKEY_REQUEST_TIMEOUT_MS: 15000;
+/**
+ * Per-attempt timeout for a BATCH describe call (NEC-013 / AC-018f.4). A batch
+ * completion is roughly 20K input tokens and multi-K output tokens
+ * (`brooding-technical-specification.md`), for which the 15s solo timeout is
+ * tight enough to produce a systematic all-failed-then-solo-storm path; solo
+ * calls (one small-to-medium file) keep {@link PORTKEY_REQUEST_TIMEOUT_MS}.
+ */
+export declare const PORTKEY_BATCH_REQUEST_TIMEOUT_MS: 60000;
+export interface ChatMessage {
+    readonly role: "system" | "user" | "assistant";
+    readonly content: string;
+}
+export interface PortkeyUsage {
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly cacheReadInputTokens: number;
+}
+export interface DescribeViaPortkeyResult {
+    readonly content: string;
+    readonly model: string;
+    readonly usage: PortkeyUsage;
+    /**
+     * The gateway's `choices[0].finish_reason` (e.g. `"stop"`, `"length"`), or
+     * `null` when absent/unparseable. `"length"` means the completion was
+     * truncated by the token cap (NEC-013 / AC-018f.3) - distinct from a
+     * malformed-but-complete response.
+     */
+    readonly finishReason: string | null;
+}
+export interface DescribeViaPortkeyRequest {
+    readonly messages: readonly ChatMessage[];
+    /** Explicit model wins over configured `activeModel` (AC-2). */
+    readonly model?: string;
+    readonly maxTokens?: number;
+    /** Per-attempt timeout override (ms); defaults to {@link PORTKEY_REQUEST_TIMEOUT_MS} when omitted. */
+    readonly timeoutMs?: number;
+}
+/** Injectable fetch seam (mirrors honeycomb's `FetchLike`). */
+export type PortkeyFetch = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+    signal?: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    text(): Promise<string>;
+}>;
+export interface DescribeViaPortkeyDeps {
+    readonly portkey: PortkeyEnabled;
+    readonly fetch?: PortkeyFetch;
+    readonly url?: string;
+    readonly maxAttempts?: number;
+    readonly retryBackoffMs?: number;
+    /** Per-attempt request timeout (ms) before the attempt aborts (default {@link PORTKEY_REQUEST_TIMEOUT_MS}). */
+    readonly timeoutMs?: number;
+    /** Injectable sleep for deterministic retry tests. */
+    sleep?(ms: number): Promise<void>;
+}
+/**
+ * Typed failure from {@link describeViaPortkey}. The message is a short status
+ * string only; the API key is never included.
+ */
+export declare class PortkeyTransportError extends Error {
+    readonly statusCode: number;
+    constructor(statusCode: number, message: string);
+}
+/**
+ * POST a chat-completions request through Portkey and return the joined assistant text.
+ * Resolves the model as: explicit arg > configured `activeModel` > `gemini-2.5-flash`.
+ */
+export declare function describeViaPortkey(request: DescribeViaPortkeyRequest, deps: DescribeViaPortkeyDeps): Promise<DescribeViaPortkeyResult>;
+//# sourceMappingURL=transport.d.ts.map

package/dist/portkey/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../src/portkey/transport.ts"],"names":[],"mappings":"AAcA,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAExE,iEAAiE;AACjE,eAAO,MAAM,0BAA0B,EAAG,IAAa,CAAC;AAExD,mFAAmF;AACnF,eAAO,MAAM,0BAA0B,aAAqC,CAAC;AAE7E,2FAA2F;AAC3F,eAAO,MAAM,oBAAoB,EAAG,CAAU,CAAC;AAE/C,0FAA0F;AAC1F,eAAO,MAAM,wBAAwB,EAAG,GAAY,CAAC;AAErD;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,EAAG,KAAe,CAAC;AAE1D;;;;;;GAMG;AACH,eAAO,MAAM,gCAAgC,EAAG,KAAe,CAAC;AAEhE,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;IAC/C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;CACvC;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CACtC;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,QAAQ,EAAE,SAAS,WAAW,EAAE,CAAC;IAC1C,gEAAgE;IAChE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,sGAAsG;IACtG,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,+DAA+D;AAC/D,MAAM,MAAM,YAAY,GAAG,CACzB,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;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAA;CAAE,CAAC,CAAC;AAEvE,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,QAAQ,CAAC,KAAK,CAAC,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,+GAA+G;IAC/G,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,sDAAsD;IACtD,KAAK,CAAC,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnC;AAED;;;GAGG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;gBAChB,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAKhD;AAkED;;;GAGG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,yBAAyB,EAClC,IAAI,EAAE,sBAAsB,GAC3B,OAAO,CAAC,wBAAwB,CAAC,CAmEnC"}

package/dist/portkey/transport.js

@@ -0,0 +1,167 @@
+/**
+ * Portkey chat-completions client for nectar description calls (PRD-010a).
+ *
+ * POSTs the OpenAI-compatible chat body to {@link PORTKEY_CHAT_COMPLETIONS_URL}
+ * with headers from {@link buildPortkeyHeaders}. Mirrors honeycomb's error mapping
+ * (status string only, never body or key) and usage surfacing (including cached
+ * read tokens when Portkey reports them). Bounded retry on 429/5xx follows the
+ * same "retry once on transient failure" discipline as `deeplake-heal.ts` (one
+ * heal-then-retry path), extended here to a small cap for rate limits.
+ */
+import { buildPortkeyHeaders, PORTKEY_CHAT_COMPLETIONS_URL, } from "./headers.js";
+import { DEFAULT_ACTIVE_MODEL } from "./config.js";
+/** Sane completion ceiling when the caller omits `maxTokens`. */
+export const PORTKEY_DEFAULT_MAX_TOKENS = 4096;
+/** HTTP statuses that trigger a bounded retry (429 rate limit + transient 5xx). */
+export const PORTKEY_RETRYABLE_STATUSES = new Set([429, 500, 502, 503, 504]);
+/** Maximum attempts including the first POST (DEFAULT - confirm before implementation). */
+export const PORTKEY_MAX_ATTEMPTS = 3;
+/** Backoff between retryable failures in ms (DEFAULT - confirm before implementation). */
+export const PORTKEY_RETRY_BACKOFF_MS = 250;
+/**
+ * Per-attempt request timeout (ms), mirroring `hive-graph/deeplake-transport.ts`'s
+ * `DEFAULT_TRANSPORT_TIMEOUT_MS` AbortController pattern: an unresponsive gateway
+ * aborts rather than hanging the caller indefinitely. Solo describe calls use
+ * this default; batch calls request the raised {@link PORTKEY_BATCH_REQUEST_TIMEOUT_MS}.
+ */
+export const PORTKEY_REQUEST_TIMEOUT_MS = 15_000;
+/**
+ * Per-attempt timeout for a BATCH describe call (NEC-013 / AC-018f.4). A batch
+ * completion is roughly 20K input tokens and multi-K output tokens
+ * (`brooding-technical-specification.md`), for which the 15s solo timeout is
+ * tight enough to produce a systematic all-failed-then-solo-storm path; solo
+ * calls (one small-to-medium file) keep {@link PORTKEY_REQUEST_TIMEOUT_MS}.
+ */
+export const PORTKEY_BATCH_REQUEST_TIMEOUT_MS = 60_000;
+/**
+ * Typed failure from {@link describeViaPortkey}. The message is a short status
+ * string only; the API key is never included.
+ */
+export class PortkeyTransportError extends Error {
+    statusCode;
+    constructor(statusCode, message) {
+        super(message);
+        this.name = "PortkeyTransportError";
+        this.statusCode = statusCode;
+    }
+}
+function defaultSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function resolveModel(explicit, activeModel) {
+    if (explicit !== undefined && explicit.trim() !== "")
+        return explicit;
+    if (activeModel.trim() !== "")
+        return activeModel;
+    return DEFAULT_ACTIVE_MODEL;
+}
+function parseUsage(raw) {
+    if (typeof raw !== "object" || raw === null) {
+        return { inputTokens: 0, outputTokens: 0, cacheReadInputTokens: 0 };
+    }
+    const u = raw;
+    const inputTokens = typeof u.prompt_tokens === "number" && Number.isFinite(u.prompt_tokens) ? u.prompt_tokens : 0;
+    const outputTokens = typeof u.completion_tokens === "number" && Number.isFinite(u.completion_tokens) ? u.completion_tokens : 0;
+    const cached = u.prompt_tokens_details?.cached_tokens;
+    const cacheReadInputTokens = typeof cached === "number" && Number.isFinite(cached) ? cached : 0;
+    return { inputTokens, outputTokens, cacheReadInputTokens };
+}
+function joinChoiceContent(choices) {
+    if (!Array.isArray(choices))
+        return "";
+    return choices
+        .map((choice) => {
+        if (typeof choice !== "object" || choice === null)
+            return "";
+        const message = choice.message;
+        const content = message?.content;
+        return typeof content === "string" ? content : "";
+    })
+        .filter((part) => part.length > 0)
+        .join("");
+}
+/** The first choice's `finish_reason` (e.g. `"stop"` / `"length"`), or `null` when absent. */
+function firstFinishReason(choices) {
+    if (!Array.isArray(choices) || choices.length === 0)
+        return null;
+    const first = choices[0];
+    if (typeof first !== "object" || first === null)
+        return null;
+    const reason = first.finish_reason;
+    return typeof reason === "string" ? reason : null;
+}
+function parseChatResponse(raw) {
+    if (typeof raw !== "object" || raw === null) {
+        throw new PortkeyTransportError(502, "portkey transport: malformed gateway response");
+    }
+    const body = raw;
+    return {
+        content: joinChoiceContent(body.choices),
+        usage: parseUsage(body.usage),
+        finishReason: firstFinishReason(body.choices),
+    };
+}
+/**
+ * POST a chat-completions request through Portkey and return the joined assistant text.
+ * Resolves the model as: explicit arg > configured `activeModel` > `gemini-2.5-flash`.
+ */
+export async function describeViaPortkey(request, deps) {
+    const doFetch = deps.fetch ?? globalThis.fetch.bind(globalThis);
+    const url = deps.url ?? PORTKEY_CHAT_COMPLETIONS_URL;
+    const maxAttempts = deps.maxAttempts ?? PORTKEY_MAX_ATTEMPTS;
+    const retryBackoffMs = deps.retryBackoffMs ?? PORTKEY_RETRY_BACKOFF_MS;
+    // Per-call request.timeoutMs (e.g. the raised batch-call value) wins over the
+    // deps-level override, which wins over the solo default (AC-018f.4).
+    const timeoutMs = request.timeoutMs ?? deps.timeoutMs ?? PORTKEY_REQUEST_TIMEOUT_MS;
+    const sleep = deps.sleep ?? defaultSleep;
+    const model = resolveModel(request.model, deps.portkey.activeModel);
+    const body = JSON.stringify({
+        model,
+        max_tokens: request.maxTokens ?? PORTKEY_DEFAULT_MAX_TOKENS,
+        messages: request.messages.map((m) => ({ role: m.role, content: m.content })),
+    });
+    const headers = buildPortkeyHeaders(deps.portkey.apiKey, deps.portkey.configId);
+    let lastStatus = 503;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        let res;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            res = await doFetch(url, { method: "POST", headers, body, signal: controller.signal });
+        }
+        catch (err) {
+            lastStatus = 503;
+            if (attempt < maxAttempts) {
+                await sleep(retryBackoffMs * attempt);
+                continue;
+            }
+            // Our own abort on `timeoutMs` surfaces as an AbortError here, same as any other
+            // network fault; never include the response body (it could echo a credential).
+            const detail = err instanceof Error ? err.name : "network error";
+            throw new PortkeyTransportError(503, `portkey transport: request failed (${detail})`);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (!res.ok) {
+            lastStatus = res.status;
+            if (attempt < maxAttempts && PORTKEY_RETRYABLE_STATUSES.has(res.status)) {
+                await sleep(retryBackoffMs * attempt);
+                continue;
+            }
+            throw new PortkeyTransportError(res.status, `portkey transport: gateway returned status ${res.status}`);
+        }
+        let raw;
+        try {
+            const text = await res.text();
+            raw = text.length > 0 ? JSON.parse(text) : null;
+        }
+        catch {
+            throw new PortkeyTransportError(502, "portkey transport: malformed gateway response");
+        }
+        const parsed = parseChatResponse(raw);
+        return { content: parsed.content, model, usage: parsed.usage, finishReason: parsed.finishReason };
+    }
+    throw new PortkeyTransportError(lastStatus, `portkey transport: gateway returned status ${lastStatus}`);
+}
+//# sourceMappingURL=transport.js.map

package/dist/portkey/transport.js.map

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

package/dist/projection/format.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Portable projection document types and canonical serialization (PRD-011a).
+ *
+ * The JSON shape matches `library/knowledge/private/data/portable-registry.md`
+ * § The file format. `content_hash` values are bare lowercase sha256 hex (64
+ * chars), aligned to `hive-graph/hash.ts`, not a `sha256-` prefixed form.
+ */
+/** Current projection schema version. Old daemons refuse to load a higher value. */
+export declare const PROJECTION_SCHEMA_VERSION = 1;
+/** Default path relative to the project root (decision #31). */
+export declare const DEFAULT_PROJECTION_REL_PATH = ".honeycomb/nectars.json";
+/** Default generator string when none is supplied. */
+export declare const DEFAULT_GENERATOR = "honeycomb-nectar@0.0.1";
+export interface ProjectionProject {
+    readonly org_id: string;
+    readonly workspace_id: string;
+    readonly project_id: string;
+}
+export interface ProjectionFileEntry {
+    readonly content_hash: string;
+    readonly path: string;
+    readonly title: string;
+    readonly description: string;
+    readonly concepts: readonly string[];
+    readonly describe_model: string;
+    readonly described_at: string;
+}
+export interface ProjectionDerivedEntry {
+    readonly from_nectar: string;
+    readonly fork_content_hash: string;
+}
+export interface PortableProjection {
+    readonly version: number;
+    readonly generated_at: string;
+    readonly generator: string;
+    readonly project: ProjectionProject;
+    readonly files: Readonly<Record<string, ProjectionFileEntry>>;
+    readonly derived: Readonly<Record<string, ProjectionDerivedEntry>>;
+}
+/** Syntactic check: 64 lowercase hex chars, no prefix (PRD-011b / hash.ts). */
+export declare function isValidContentHash(value: string): boolean;
+/** Parse JSON text into an unknown value; throws on invalid JSON. */
+export declare function parseProjectionJson(text: string): unknown;
+/**
+ * Deterministic JSON bytes: stable key order at every object level so two
+ * generations from the same store state differ only in `generated_at` (AC-7).
+ */
+export declare function canonicalSerialize(doc: PortableProjection): string;
+/** Strip `generated_at` for byte-identical comparisons (AC-7). */
+export declare function canonicalSerializeExceptGeneratedAt(doc: PortableProjection): string;
+//# sourceMappingURL=format.d.ts.map

package/dist/projection/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../src/projection/format.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,oFAAoF;AACpF,eAAO,MAAM,yBAAyB,IAAI,CAAC;AAE3C,gEAAgE;AAChE,eAAO,MAAM,2BAA2B,4BAA4B,CAAC;AAErE,sDAAsD;AACtD,eAAO,MAAM,iBAAiB,2BAA2B,CAAC;AAE1D,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;CACpC;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;IACpC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC,CAAC;IAC9D,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC,CAAC;CACpE;AAID,+EAA+E;AAC/E,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED,qEAAqE;AACrE,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEzD;AAsCD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,kBAAkB,GAAG,MAAM,CAmBlE;AAED,kEAAkE;AAClE,wBAAgB,mCAAmC,CAAC,GAAG,EAAE,kBAAkB,GAAG,MAAM,CAGnF"}

package/dist/projection/format.js

@@ -0,0 +1,81 @@
+/**
+ * Portable projection document types and canonical serialization (PRD-011a).
+ *
+ * The JSON shape matches `library/knowledge/private/data/portable-registry.md`
+ * § The file format. `content_hash` values are bare lowercase sha256 hex (64
+ * chars), aligned to `hive-graph/hash.ts`, not a `sha256-` prefixed form.
+ */
+/** Current projection schema version. Old daemons refuse to load a higher value. */
+export const PROJECTION_SCHEMA_VERSION = 1;
+/** Default path relative to the project root (decision #31). */
+export const DEFAULT_PROJECTION_REL_PATH = ".honeycomb/nectars.json";
+/** Default generator string when none is supplied. */
+export const DEFAULT_GENERATOR = "honeycomb-nectar@0.0.1";
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+/** Syntactic check: 64 lowercase hex chars, no prefix (PRD-011b / hash.ts). */
+export function isValidContentHash(value) {
+    return SHA256_HEX.test(value);
+}
+/** Parse JSON text into an unknown value; throws on invalid JSON. */
+export function parseProjectionJson(text) {
+    return JSON.parse(text);
+}
+function quoteString(s) {
+    return JSON.stringify(s);
+}
+function serializeStringArray(arr) {
+    return `[${arr.map((v) => quoteString(v)).join(",")}]`;
+}
+function serializeFileEntry(entry) {
+    const parts = [
+        `"content_hash":${quoteString(entry.content_hash)}`,
+        `"path":${quoteString(entry.path)}`,
+        `"title":${quoteString(entry.title)}`,
+        `"description":${quoteString(entry.description)}`,
+        `"concepts":${serializeStringArray(entry.concepts)}`,
+        `"describe_model":${quoteString(entry.describe_model)}`,
+        `"described_at":${quoteString(entry.described_at)}`,
+    ];
+    return `{${parts.join(",")}}`;
+}
+function serializeDerivedEntry(entry) {
+    return `{${[
+        `"from_nectar":${quoteString(entry.from_nectar)}`,
+        `"fork_content_hash":${quoteString(entry.fork_content_hash)}`,
+    ].join(",")}}`;
+}
+function serializeProject(project) {
+    return `{${[
+        `"org_id":${quoteString(project.org_id)}`,
+        `"workspace_id":${quoteString(project.workspace_id)}`,
+        `"project_id":${quoteString(project.project_id)}`,
+    ].join(",")}}`;
+}
+/**
+ * Deterministic JSON bytes: stable key order at every object level so two
+ * generations from the same store state differ only in `generated_at` (AC-7).
+ */
+export function canonicalSerialize(doc) {
+    const fileKeys = Object.keys(doc.files).sort();
+    const filesBody = fileKeys
+        .map((k) => `${quoteString(k)}:${serializeFileEntry(doc.files[k])}`)
+        .join(",");
+    const derivedKeys = Object.keys(doc.derived).sort();
+    const derivedBody = derivedKeys
+        .map((k) => `${quoteString(k)}:${serializeDerivedEntry(doc.derived[k])}`)
+        .join(",");
+    return `{${[
+        `"version":${doc.version}`,
+        `"generated_at":${quoteString(doc.generated_at)}`,
+        `"generator":${quoteString(doc.generator)}`,
+        `"project":${serializeProject(doc.project)}`,
+        `"files":{${filesBody}}`,
+        `"derived":{${derivedBody}}`,
+    ].join(",")}}\n`;
+}
+/** Strip `generated_at` for byte-identical comparisons (AC-7). */
+export function canonicalSerializeExceptGeneratedAt(doc) {
+    const without = { ...doc, generated_at: "1970-01-01T00:00:00.000Z" };
+    return canonicalSerialize(without);
+}
+//# sourceMappingURL=format.js.map

package/dist/projection/format.js.map

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