@stigmer/runner 3.12.7 → 3.12.9

package/src/shared/memory-retrieval.ts

@@ -0,0 +1,383 @@
+/**
+ * Semantic selection of recalled memories (stigmer/stigmer#293 Phase 3a,
+ * DD-008): when a subject's confirmed-fact set outgrows what wholesale
+ * injection should carry, select the most relevant facts for THIS
+ * execution instead of injecting everything.
+ *
+ * Sibling of recalled-memories.ts (which owns presentation) — this module
+ * owns SELECTION: which subset of the server-composed candidate set
+ * (`spec.recalled_memories`, the auditable snapshot both editions' compose
+ * steps stamp) actually rides the prompt. The compose steps never change;
+ * selection is a runner concern because the runner owns prompt assembly,
+ * provider credentials, and the metered proxy lane (DD-008 D1 — the
+ * titling-convergence doctrine: control-plane-adjacent LLM work runs once,
+ * in the shared runner, for both editions).
+ *
+ * Mechanism (DD-008 D2/D3): embed-on-read, no stored vectors anywhere.
+ * Selection activates ONLY above RETRIEVAL_K candidates; below that,
+ * top-k degenerates to wholesale, so no embeddings call is made and the
+ * shipped Phase 2 path runs untouched. When active: ONE batched
+ * embeddings call (query + all candidates), in-process cosine ranking,
+ * top-k by relevance, presented in snapshot order (relevance order would
+ * carry no information the model needs and would churn the prompt prefix).
+ * The query is the execution's `spec.message` — the current turn.
+ *
+ * The audit contract (DD-008 D5): the selection outcome is recorded in a
+ * runner-owned `RecalledMemoriesReport` on the execution status (the
+ * streaming_usage posture — one writer, written at prompt build). A report
+ * is returned whenever facts are injected, wholesale or selected; when
+ * nothing is injected (recall absent/disabled/empty) there is no report —
+ * absent report = wholesale, true by construction, so pre-3a executions
+ * read identically.
+ *
+ * Written-once across re-invocations: the same execution's prompt is
+ * rebuilt on approval resume (native) and fresh-agent recovery (cursor).
+ * Re-running selection there could pick a DIFFERENT subset mid-execution —
+ * so when the loaded execution already carries a report, this module
+ * REPLAYS it (selected ids resolved against the snapshot, or wholesale
+ * for a selection_active=false report) instead of re-embedding. Selection
+ * is computed at most once per execution, by construction.
+ *
+ * Failure posture: selection is an optimization. ANY failure — no
+ * embedder, HTTP error, timeout, malformed response — degrades to
+ * wholesale injection with a selection_active=false report, never a
+ * failed or degraded execution (DD-008 D3). Deployments with no
+ * embeddings-capable credential (Anthropic-only, Cursor-only OSS) run
+ * Phase 2 behavior unchanged, forever.
+ */
+
+import { create } from "@bufbuild/protobuf";
+import type { RecalledMemories } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/spec_pb";
+import {
+  RecalledMemoriesReportSchema,
+  type RecalledMemoriesReport,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type { RecalledMemoriesContent } from "./recalled-memories.js";
+import { resolveProxyBaseUrl, buildProxyHeaders } from "./llm-proxy.js";
+import { checkDirectCredentials } from "./llm-backend.js";
+import { getRunnerSecret } from "./runner-credential-store.js";
+
+/**
+ * Selection activates only when the candidate set EXCEEDS this many facts;
+ * at or below it, top-k degenerates to wholesale and no embeddings call is
+ * made. 20 is comfortably above the dozens-scale where wholesale is fine
+ * (activation is rare) and comfortably below the 100-record cap (activation
+ * is meaningful): at 500-char facts, 20 facts ≈ 10KB of prompt. One
+ * constant, one place, deliberately not adaptive or per-org configurable
+ * in v1 (DD-008 D3).
+ */
+export const RETRIEVAL_K = 20;
+
+/**
+ * The v1 embedder (DD-008 D4). OpenAI-only: resolved through the Stigmer
+ * proxy when one is configured (cloud — platform key, metered), else the
+ * operator's direct OpenAI key (OSS). NOTE: llm-proxy's `inferProvider`
+ * does not know the `text-*` prefix — this module never infers; the
+ * provider is fixed alongside the model.
+ */
+export const EMBEDDING_MODEL = "text-embedding-3-small";
+
+/**
+ * Upper bound on the query text sent to the embedder. Facts are write-time
+ * capped at 500 chars, but the query is `spec.message` — unbounded. A giant
+ * pasted message would blow the embedder's per-input token limit (8192 for
+ * text-embedding-3-small) and 400 the WHOLE batched call, silently forcing
+ * wholesale on exactly the executions where selection matters. 20K chars
+ * sits safely under the limit at worst-case chars-per-token; selection
+ * intent is dominated by the message head, and a truncated query beats no
+ * selection.
+ */
+export const QUERY_MAX_CHARS = 20_000;
+
+/**
+ * Bound on the single embeddings round trip. Generous relative to the
+ * observed 200–400ms typical latency: this exists to keep a hung
+ * connection from stalling prompt build, not to race the provider.
+ */
+const EMBED_TIMEOUT_MS = 15_000;
+
+/** The OpenAI SDK-default base, used only in direct (unproxied) mode. */
+const DIRECT_OPENAI_BASE_URL = "https://api.openai.com/v1";
+
+/**
+ * One batched embeddings call: one vector per input, in input order.
+ * The seam unit tests inject through, and the boundary a stored-vector
+ * optimization would slot behind if caps ever grow (DD-008 D2).
+ */
+export type EmbedFn = (inputs: readonly string[]) => Promise<number[][]>;
+
+export interface MemoryRetrievalOptions {
+  /** Null/undefined when the deployment has no proxy (direct mode). */
+  readonly proxyEndpoint: string | null | undefined;
+  /** Bearer for proxy mode; unused in direct mode. */
+  readonly stigmerToken: string | null | undefined;
+  /** Scopes the proxied call for FGA authorization and billing attribution. */
+  readonly executionId: string;
+  /**
+   * The report a PREVIOUS invocation of this same execution recorded, if
+   * any (`execution.status.recalled_memories_report`). Presence replays
+   * the recorded outcome instead of re-selecting — the written-once rule.
+   */
+  readonly priorReport?: RecalledMemoriesReport;
+  /** Test seam; defaults to the proxy/direct embedder resolution. */
+  readonly embed?: EmbedFn;
+}
+
+export interface MemorySelectionResult {
+  /**
+   * The facts to inject, in snapshot order — undefined when recall is
+   * absent, disabled, or empty (render nothing, exactly the
+   * readRecalledMemories contract).
+   */
+  readonly content: RecalledMemoriesContent | undefined;
+  /**
+   * The injection outcome to stamp on the execution status. Undefined
+   * exactly when `content` is undefined: no injection, no report.
+   */
+  readonly report: RecalledMemoriesReport | undefined;
+}
+
+/** A candidate fact: the snapshot entry with its audit identity intact. */
+interface Candidate {
+  readonly memoryId: string;
+  readonly content: string;
+}
+
+/**
+ * Select the facts to inject for one execution.
+ *
+ * This is the ONE entry point both harnesses call at prompt build, replacing
+ * their direct `readRecalledMemories` reads on the injection path (the read
+ * function remains the presentation-side authority; this module reads the
+ * proto itself because selection needs `memory_id`, which the render
+ * boundary deliberately strips).
+ *
+ * Never throws: every failure path returns wholesale.
+ */
+export async function selectRecalledFacts(
+  recalled: RecalledMemories | undefined,
+  queryText: string,
+  options: MemoryRetrievalOptions,
+): Promise<MemorySelectionResult> {
+  const candidates = readCandidates(recalled);
+  if (candidates.length === 0) {
+    return { content: undefined, report: undefined };
+  }
+
+  // Written-once: a prior invocation of this execution already decided.
+  if (options.priorReport !== undefined) {
+    const replayed = replayReport(candidates, options.priorReport);
+    if (replayed !== undefined) {
+      return replayed;
+    }
+    // Unreplayable (recorded ids missing from the immutable snapshot —
+    // structurally impossible, defended anyway): fall through and select
+    // fresh rather than inject nothing.
+    log(
+      `prior report for execution ${options.executionId} did not resolve ` +
+      `against the snapshot; re-selecting`,
+    );
+  }
+
+  if (candidates.length <= RETRIEVAL_K) {
+    return wholesale(candidates);
+  }
+
+  const embed = options.embed ?? resolveEmbedder(options);
+  if (embed === undefined) {
+    // No embeddings-capable credential: the recorded no-embedder posture
+    // (DD-008 D4) — Phase 2 behavior, honestly reported.
+    return wholesale(candidates);
+  }
+
+  try {
+    const query = queryText.slice(0, QUERY_MAX_CHARS);
+    const vectors = await embed([query, ...candidates.map((c) => c.content)]);
+    if (vectors.length !== candidates.length + 1) {
+      throw new Error(
+        `embedder returned ${vectors.length} vectors for ` +
+        `${candidates.length + 1} inputs`,
+      );
+    }
+    const [queryVector, ...factVectors] = vectors;
+    const selected = topKBySimilarity(queryVector, factVectors, RETRIEVAL_K);
+    return {
+      content: { facts: selected.map((i) => candidates[i].content) },
+      report: create(RecalledMemoriesReportSchema, {
+        selectionActive: true,
+        injectedMemoryIds: selected.map((i) => candidates[i].memoryId),
+        embeddingModel: EMBEDDING_MODEL,
+      }),
+    };
+  } catch (err) {
+    log(
+      `selection failed for execution ${options.executionId}, degrading to ` +
+      `wholesale: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return wholesale(candidates);
+  }
+}
+
+/**
+ * The snapshot's renderable candidates, in snapshot order. Same semantics
+ * as readRecalledMemories (disabled → none; blank contents dropped
+ * defensively) but keeping `memory_id` — the report's audit link.
+ */
+function readCandidates(recalled: RecalledMemories | undefined): Candidate[] {
+  if (!recalled?.enabled) {
+    return [];
+  }
+  return (recalled.facts ?? [])
+    .map((fact) => ({
+      memoryId: fact.memoryId ?? "",
+      content: fact.content?.trim() ?? "",
+    }))
+    .filter((c) => c.content !== "");
+}
+
+/**
+ * Replay a previously recorded outcome so a re-invocation injects exactly
+ * what the first invocation did. A selection_active=false report replays
+ * as wholesale (including the case where a transient embed failure was
+ * recorded — retrying could select a subset and diverge the prompt).
+ * Returns undefined when a recorded id no longer resolves.
+ */
+function replayReport(
+  candidates: Candidate[],
+  prior: RecalledMemoriesReport,
+): MemorySelectionResult | undefined {
+  if (!prior.selectionActive) {
+    return wholesale(candidates);
+  }
+  const byId = new Map(candidates.map((c) => [c.memoryId, c.content]));
+  const facts: string[] = [];
+  for (const id of prior.injectedMemoryIds) {
+    const content = byId.get(id);
+    if (content === undefined) {
+      return undefined;
+    }
+    facts.push(content);
+  }
+  if (facts.length === 0) {
+    return undefined;
+  }
+  return { content: { facts }, report: prior };
+}
+
+/** Wholesale injection of the full candidate set, honestly reported. */
+function wholesale(candidates: Candidate[]): MemorySelectionResult {
+  return {
+    content: { facts: candidates.map((c) => c.content) },
+    report: create(RecalledMemoriesReportSchema, { selectionActive: false }),
+  };
+}
+
+/**
+ * The credential lanes, in the platform's standing precedence (the
+ * titling-lane idiom): proxy when configured — the runner authenticates
+ * with its Stigmer token and the proxy owns the provider key — else the
+ * operator's direct OpenAI key, else no embedder.
+ */
+function resolveEmbedder(options: MemoryRetrievalOptions): EmbedFn | undefined {
+  if (options.proxyEndpoint) {
+    return fetchEmbedder(
+      resolveProxyBaseUrl(options.proxyEndpoint, "openai"),
+      buildProxyHeaders(options.stigmerToken ?? "", {
+        executionId: options.executionId,
+      }),
+    );
+  }
+  if (checkDirectCredentials("openai") === null) {
+    return fetchEmbedder(DIRECT_OPENAI_BASE_URL, {
+      Authorization: `Bearer ${getRunnerSecret("OPENAI_API_KEY") ?? ""}`,
+    });
+  }
+  return undefined;
+}
+
+/**
+ * The real embedder: one POST {base}/embeddings. A plain typed fetch, not
+ * LangChain's OpenAIEmbeddings — the SDK wrapper discards the response
+ * `usage` block and adds nothing over a single request. Proxy-side
+ * metering reads the JSON usage from the relayed body.
+ */
+function fetchEmbedder(baseUrl: string, headers: Record<string, string>): EmbedFn {
+  return async (inputs) => {
+    const response = await fetch(`${baseUrl}/embeddings`, {
+      method: "POST",
+      headers: { ...headers, "Content-Type": "application/json" },
+      body: JSON.stringify({ model: EMBEDDING_MODEL, input: inputs }),
+      signal: AbortSignal.timeout(EMBED_TIMEOUT_MS),
+    });
+    if (!response.ok) {
+      const body = await response.text().catch(() => "");
+      throw new Error(
+        `embeddings request failed: HTTP ${response.status} ${body.slice(0, 300)}`,
+      );
+    }
+    const parsed = (await response.json()) as {
+      data?: Array<{ index?: number; embedding?: number[] }>;
+    };
+    if (!Array.isArray(parsed.data)) {
+      throw new Error("embeddings response carries no data array");
+    }
+    // Place by the response's own index field — the API documents input
+    // order, but the contract names the index as authoritative.
+    const vectors: number[][] = new Array(inputs.length);
+    for (const item of parsed.data) {
+      const index = item.index ?? -1;
+      if (index < 0 || index >= inputs.length || !Array.isArray(item.embedding)) {
+        throw new Error("embeddings response entry is malformed");
+      }
+      vectors[index] = item.embedding;
+    }
+    if (vectors.some((v) => v === undefined)) {
+      throw new Error("embeddings response is missing entries");
+    }
+    return vectors;
+  };
+}
+
+/**
+ * Indices of the top-k facts by cosine similarity to the query, returned
+ * ASCENDING — i.e. re-sorted to snapshot order (DD-008 D3: selection is by
+ * relevance, presentation stays oldest-first). Ties break toward the lower
+ * snapshot index, so equal scores never reorder across invocations.
+ */
+function topKBySimilarity(
+  queryVector: number[],
+  factVectors: number[][],
+  k: number,
+): number[] {
+  return factVectors
+    .map((vector, index) => ({ index, score: cosineSimilarity(queryVector, vector) }))
+    .sort((a, b) => b.score - a.score || a.index - b.index)
+    .slice(0, k)
+    .map((entry) => entry.index)
+    .sort((a, b) => a - b);
+}
+
+/**
+ * Plain cosine. OpenAI embeddings arrive unit-normalized (a dot product
+ * would suffice today), but normalizing here keeps ranking correct under
+ * any future embedder without a silent provider assumption.
+ */
+function cosineSimilarity(a: number[], b: number[]): number {
+  let dot = 0;
+  let normA = 0;
+  let normB = 0;
+  const length = Math.min(a.length, b.length);
+  for (let i = 0; i < length; i++) {
+    dot += a[i] * b[i];
+    normA += a[i] * a[i];
+    normB += b[i] * b[i];
+  }
+  if (normA === 0 || normB === 0) {
+    return 0;
+  }
+  return dot / (Math.sqrt(normA) * Math.sqrt(normB));
+}
+
+function log(msg: string): void {
+  console.warn(`[memory-retrieval] ${msg}`);
+}

package/src/shared/runner-credential-keys.ts

@@ -63,7 +63,8 @@ export const RUNNER_CREDENTIAL_ENV_KEYS: readonly string[] = [
  * rotation bookkeeping, not secrets.
  */
 export const RUNNER_ENCRYPTION_ENV_KEYS: readonly string[] = [
-  // Temporal payload-encryption keys (encryption/config.ts). An agent that
+  // Temporal payload-encryption keys (@stigmer/temporal-codecs' encryption
+  // config, read through the injected getRunnerSecret). An agent that
   // reads these could decrypt the runner's Temporal history payloads.
   "STIGMER_PAYLOAD_ENCRYPTION_KEY",
   "STIGMER_PAYLOAD_ENCRYPTION_SECONDARY_KEY",

package/src/shared/tool-kind.ts

@@ -14,6 +14,8 @@
 
 import { ToolKind } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 
+import { MEMORY_ATTACHMENT_SLUG } from "./memory-attachment.js";
+
 // Bare tool name -> ToolKind, covering both harness naming conventions. A name
 // found here is a built-in and wins over a non-empty mcp_server_slug (an MCP
 // server is not expected to shadow a built-in name; matching the legacy resolver).
@@ -81,6 +83,14 @@ const TOOL_NAME_TO_KIND: ReadonlyMap<string, ToolKind> = new Map([
  * back to a name lookup, so this is never worse than no classification).
  */
 export function classifyTool(name: string, mcpServerSlug?: string): ToolKind {
+  // The first-party remember tool (DD-005), slug-scoped on purpose: it is
+  // served by the synthesized memory attachment, so only that reserved
+  // slug earns the MEMORY kind (and its consent-chip rendering) — a
+  // third-party MCP server's coincidental `remember` stays a plain MCP
+  // tool, and a bare `remember` with no slug stays unclassified.
+  if (name === "remember" && mcpServerSlug === MEMORY_ATTACHMENT_SLUG) {
+    return ToolKind.MEMORY;
+  }
   const builtin = TOOL_NAME_TO_KIND.get(name);
   if (builtin !== undefined) {
     return builtin;

package/dist/claimcheck/compressor.d.ts

@@ -1,2 +0,0 @@
-export declare function compress(data: Buffer): Buffer<ArrayBuffer>;
-export declare function decompress(data: Buffer): Buffer<ArrayBuffer>;

package/dist/claimcheck/compressor.js

@@ -1,8 +0,0 @@
-import { gzipSync, gunzipSync } from "node:zlib";
-export function compress(data) {
-    return gzipSync(data);
-}
-export function decompress(data) {
-    return gunzipSync(data);
-}
-//# sourceMappingURL=compressor.js.map

package/dist/claimcheck/compressor.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"compressor.js","sourceRoot":"","sources":["../../src/claimcheck/compressor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAEjD,MAAM,UAAU,QAAQ,CAAC,IAAY;IACnC,OAAO,QAAQ,CAAC,IAAI,CAAwB,CAAC;AAC/C,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,OAAO,UAAU,CAAC,IAAI,CAAwB,CAAC;AACjD,CAAC"}

package/dist/claimcheck/config.d.ts

@@ -1,7 +0,0 @@
-export interface ClaimcheckConfig {
-    readonly enabled: boolean;
-    readonly thresholdBytes: number;
-    readonly compressionEnabled: boolean;
-    readonly keyPrefix: string;
-}
-export declare function loadClaimcheckConfig(): ClaimcheckConfig;

package/dist/claimcheck/config.js

@@ -1,10 +0,0 @@
-const DEFAULT_THRESHOLD_BYTES = 128 * 1024; // 128KB
-export function loadClaimcheckConfig() {
-    return {
-        enabled: process.env.CLAIMCHECK_ENABLED === "true",
-        thresholdBytes: parseInt(process.env.CLAIMCHECK_THRESHOLD_BYTES ?? String(DEFAULT_THRESHOLD_BYTES), 10),
-        compressionEnabled: process.env.CLAIMCHECK_COMPRESSION_ENABLED !== "false",
-        keyPrefix: process.env.CLAIMCHECK_KEY_PREFIX ?? "claimcheck/",
-    };
-}
-//# sourceMappingURL=config.js.map

package/dist/claimcheck/config.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/claimcheck/config.ts"],"names":[],"mappings":"AAOA,MAAM,uBAAuB,GAAG,GAAG,GAAG,IAAI,CAAC,CAAC,QAAQ;AAEpD,MAAM,UAAU,oBAAoB;IAClC,OAAO;QACL,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,kBAAkB,KAAK,MAAM;QAClD,cAAc,EAAE,QAAQ,CACtB,OAAO,CAAC,GAAG,CAAC,0BAA0B,IAAI,MAAM,CAAC,uBAAuB,CAAC,EACzE,EAAE,CACH;QACD,kBAAkB,EAAE,OAAO,CAAC,GAAG,CAAC,8BAA8B,KAAK,OAAO;QAC1E,SAAS,EAAE,OAAO,CAAC,GAAG,CAAC,qBAAqB,IAAI,aAAa;KAC9D,CAAC;AACJ,CAAC"}

package/dist/claimcheck/index.d.ts

@@ -1,3 +0,0 @@
-export { ClaimcheckPayloadCodec } from "./payload-codec.js";
-export { loadClaimcheckConfig, type ClaimcheckConfig } from "./config.js";
-export { compress, decompress } from "./compressor.js";

package/dist/claimcheck/index.js

@@ -1,4 +0,0 @@
-export { ClaimcheckPayloadCodec } from "./payload-codec.js";
-export { loadClaimcheckConfig } from "./config.js";
-export { compress, decompress } from "./compressor.js";
-//# sourceMappingURL=index.js.map

package/dist/claimcheck/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/claimcheck/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,oBAAoB,EAAyB,MAAM,aAAa,CAAC;AAC1E,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/claimcheck/payload-codec.d.ts

@@ -1,23 +0,0 @@
-/**
- * Temporal PayloadCodec that transparently offloads large payloads to
- * external storage (ArtifactStorage). Payloads below the threshold pass
- * through unchanged. Payloads at or above the threshold are compressed
- * (optional), uploaded, and replaced with a small reference marker.
- *
- * On decode, markers are detected, the original payload is downloaded
- * and decompressed, and the original bytes are restored — transparent
- * to workflow/activity code.
- */
-import type { Payload, PayloadCodec } from "@temporalio/common";
-import type { ArtifactStorage } from "../shared/artifact-storage.js";
-import type { ClaimcheckConfig } from "./config.js";
-export declare class ClaimcheckPayloadCodec implements PayloadCodec {
-    private readonly storage;
-    private readonly config;
-    constructor(storage: ArtifactStorage, config: ClaimcheckConfig);
-    encode(payloads: Payload[]): Promise<Payload[]>;
-    decode(payloads: Payload[]): Promise<Payload[]>;
-    private encodePayload;
-    private decodePayload;
-    private isClaimcheckPayload;
-}

package/dist/claimcheck/payload-codec.js

@@ -1,105 +0,0 @@
-/**
- * Temporal PayloadCodec that transparently offloads large payloads to
- * external storage (ArtifactStorage). Payloads below the threshold pass
- * through unchanged. Payloads at or above the threshold are compressed
- * (optional), uploaded, and replaced with a small reference marker.
- *
- * On decode, markers are detected, the original payload is downloaded
- * and decompressed, and the original bytes are restored — transparent
- * to workflow/activity code.
- */
-import { randomUUID } from "node:crypto";
-import { compress, decompress } from "./compressor.js";
-const MARKER_METADATA_KEY = "encoding";
-const MARKER_ENCODING_VALUE = "binary/claimcheck";
-export class ClaimcheckPayloadCodec {
-    storage;
-    config;
-    constructor(storage, config) {
-        this.storage = storage;
-        this.config = config;
-    }
-    async encode(payloads) {
-        return Promise.all(payloads.map((p) => this.encodePayload(p)));
-    }
-    async decode(payloads) {
-        return Promise.all(payloads.map((p) => this.decodePayload(p)));
-    }
-    async encodePayload(payload) {
-        const data = payload.data;
-        if (!data || data.length < this.config.thresholdBytes) {
-            return payload;
-        }
-        const originalBuf = Buffer.from(data);
-        let uploadBuf = originalBuf;
-        let compressed = false;
-        if (this.config.compressionEnabled) {
-            const compressedBuf = compress(originalBuf);
-            if (compressedBuf.length < originalBuf.length) {
-                uploadBuf = compressedBuf;
-                compressed = true;
-            }
-        }
-        const key = `${this.config.keyPrefix}${randomUUID()}`;
-        await this.storage.upload(key, uploadBuf, "application/octet-stream");
-        const marker = {
-            key,
-            size: data.length,
-            compressed,
-            metadata: serializeMetadata(payload.metadata),
-        };
-        return {
-            metadata: {
-                [MARKER_METADATA_KEY]: Buffer.from(MARKER_ENCODING_VALUE),
-            },
-            data: Buffer.from(JSON.stringify(marker)),
-        };
-    }
-    async decodePayload(payload) {
-        if (!this.isClaimcheckPayload(payload)) {
-            return payload;
-        }
-        const marker = JSON.parse(Buffer.from(payload.data).toString("utf-8"));
-        let rawBuf;
-        try {
-            rawBuf = await this.storage.download(marker.key);
-        }
-        catch (err) {
-            // Preserve the claimcheck-scoped error contract; the shared download error
-            // already carries the HTTP status (proxy) or the miss (local) as the cause.
-            const cause = err instanceof Error ? err.message : String(err);
-            throw new Error(`Claimcheck retrieve failed for key ${marker.key}: ${cause}`);
-        }
-        const dataBuf = marker.compressed ? decompress(rawBuf) : rawBuf;
-        return {
-            metadata: marker.metadata
-                ? deserializeMetadata(marker.metadata)
-                : payload.metadata,
-            data: dataBuf,
-        };
-    }
-    isClaimcheckPayload(payload) {
-        const encoding = payload.metadata?.[MARKER_METADATA_KEY];
-        if (!encoding)
-            return false;
-        return Buffer.from(encoding).toString("utf-8") === MARKER_ENCODING_VALUE;
-    }
-}
-function serializeMetadata(metadata) {
-    if (!metadata)
-        return undefined;
-    const out = {};
-    for (const [key, value] of Object.entries(metadata)) {
-        if (value)
-            out[key] = Buffer.from(value).toString("base64");
-    }
-    return out;
-}
-function deserializeMetadata(metadata) {
-    const out = {};
-    for (const [key, value] of Object.entries(metadata)) {
-        out[key] = Buffer.from(value, "base64");
-    }
-    return out;
-}
-//# sourceMappingURL=payload-codec.js.map

package/dist/claimcheck/payload-codec.js.map

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

package/dist/encryption/config.d.ts

@@ -1,64 +0,0 @@
-/**
- * Payload-encryption configuration (stigmer-cloud#227, stigmer#398).
- *
- * Two key sources, strict precedence:
- *
- *   1. Environment (STIGMER_PAYLOAD_ENCRYPTION_KEY(_ID)) — the operator's
- *      explicit choice: self-hosted deployments sharing one key with their
- *      server, and cloud sandboxes injected with the platform key. When the
- *      env key is set, bootstrap-delivered material is ignored entirely.
- *   2. Bootstrap-delivered — server-managed per-identity keys handed to
- *      desktop-class runners by getRunnerBootstrapConfig. Held in memory
- *      only; persistence lives server-side, which is what makes Temporal
- *      replay work across runner restarts (every boot re-fetches the SAME
- *      key).
- *
- * Encryption is enabled iff a key is present from either source — the same
- * enabled-iff-configured pattern as the claim-check codec. A malformed key
- * fails the boot rather than silently running plaintext: an operator who set
- * the key (or a server that minted one) intended history to be encrypted.
- *
- * Key rotation: payloads carry the id of the key that encrypted them.
- * During a rotation window the previous key stays readable via the
- * secondary pair while new payloads are written under the primary key.
- * Workers capture keys at construction, so a rotated bootstrap key lands
- * on the next runner boot — there is no live re-key.
- */
-export interface EncryptionKey {
-    readonly keyId: string;
-    /** 32-byte AES-256 key. */
-    readonly key: Buffer;
-}
-export interface PayloadEncryptionConfig {
-    /** Key used to encrypt outgoing payloads (and decrypt its own). */
-    readonly primary: EncryptionKey;
-    /** Decrypt-only key accepted during rotation windows. */
-    readonly secondary?: EncryptionKey;
-}
-/**
- * Server-managed key material delivered by getRunnerBootstrapConfig.
- * Structurally mirrors {@link BootstrapPayloadEncryptionKeys} in
- * stigmer-client.ts — declared here so this leaf module stays free of
- * client imports.
- */
-export interface BootstrapKeyMaterial {
-    readonly key: string;
-    readonly keyId?: string;
-    readonly secondaryKey?: string;
-    readonly secondaryKeyId?: string;
-}
-/**
- * Returns the encryption config, or undefined when encryption is not
- * configured (the codec is then simply not installed).
- *
- * Source precedence: the env key wins outright; bootstrap-delivered
- * material applies only when no env key is set (see the module doc).
- *
- * @throws when a key is present but malformed, or a key id is missing —
- *   key misconfiguration must stop the boot, not degrade to plaintext.
- *   This applies equally to bootstrap material: a server that hands out
- *   a bad key or omits its id has broken the protocol contract, and
- *   running plaintext against a server that manages keys would silently
- *   defeat the feature.
- */
-export declare function loadPayloadEncryptionConfig(bootstrap?: BootstrapKeyMaterial): PayloadEncryptionConfig | undefined;