@stigmer/server 3.14.0-dev.20260910084630

package/src/domain/executioncontext/resolve-values-for-caller.ts

@@ -0,0 +1,236 @@
+/**
+ * resolveValuesForCaller — ports
+ * pkg/domain/executioncontext/controller/resolve_values_for_caller.go:
+ * decides, by presented credential, whether a getByExecutionId response
+ * carries decrypted or redacted secret values, and applies the transform
+ * in place. The OSS mirror of the cloud edition's
+ * ResolveExecutionContextValuesForCaller (oss#535, porting the
+ * stigmer-cloud#152 contract: no read RPC hands plaintext secrets to a
+ * caller outside the runner lane).
+ *
+ * # The lane
+ *
+ * getByExecutionId is the runner's secret-delivery path. The runner
+ * distinguishes itself with an execution-scoped token minted by
+ * getRunnerScopedToken and presented as a Bearer authorization header
+ * (the same header shape a cloud runner uses for its sandbox credential).
+ * Decrypt requires the FULL binding: a valid, unexpired token whose
+ * execution_id claim equals this EC's spec.execution_id. Everything else
+ * — no header, malformed or expired token, or a token minted for a
+ * different execution — falls closed to the same redaction
+ * get/getByReference apply, as a SUCCESSFUL response, not an error.
+ *
+ * Token verification lives HERE, in the domain, not on the identity
+ * chassis (O2, 20260827.01): the runner token is a lane discriminator,
+ * not a caller identity — the chassis deliberately lets it fall through
+ * to the trusted-local identity (ruling Q6), and this is the one RPC
+ * that reads the raw header — exactly the consumer the runnerauth module
+ * header reserves ("the executioncontext resolve step"). The
+ * redaction-as-success contract is pinned by the conformance suites and
+ * must survive every future verifier: a runner token is NEVER an
+ * authentication credential.
+ *
+ * # Decrypt error doctrine (the oss#405 runtime-resolution doctrine,
+ * # arms per the two-armed taxonomy in encryption/errors.ts)
+ *
+ *   - The value-scoped arm (InvalidCiphertextError family —
+ *     tampered/truncated/wrong-key) is scoped to one value: WARN and
+ *     drop that key rather than failing the read.
+ *   - The infrastructure arm (EncryptionUnavailableError, incl. its
+ *     keyless EncryptionDisabledError case) fails the request: the
+ *     stored ciphertext may be perfectly valid (key file lost, codec's
+ *     key provider unreachable, version with no codec here), and
+ *     dropping it would start the execution silently missing a
+ *     credential — a confusing downstream failure instead of a clear one
+ *     here.
+ *   - Legacy pre-oss#535 plaintext rows pass through undecorated (decrypt
+ *     only runs on isEncrypted values), so old stores serve without
+ *     migration.
+ */
+import type { HandlerContext } from "@connectrpc/connect";
+
+import type { ExecutionContext } from "@stigmer/protos/ai/stigmer/agentic/executioncontext/v1/api_pb";
+
+import type { Logger } from "../../boot/logger.js";
+import { EncryptionUnavailableError } from "../../encryption/encryption.js";
+import type { SecretService } from "../../encryption/encryption.js";
+import { internalError } from "../../pipeline/errors.js";
+import { parseBearerToken } from "../../pipeline/interceptors/auth.js";
+import type { RunnerCredentialProvider } from "../../runnerauth/runner-credential-provider.js";
+import { TOKEN_TYPE_EXECUTION_SCOPED } from "../../runnerauth/runnerauth.js";
+import { encryptionKeyMissingMessage } from "./constants.js";
+import { redactExecutionContextSecrets } from "./redact.js";
+
+export interface ResolveValuesDeps {
+  readonly logger: Logger;
+  readonly secretService: SecretService;
+  readonly runnerAuthService: RunnerCredentialProvider;
+}
+
+/**
+ * Applies the credential-dispatched transform in place: decrypt for a
+ * scope-bound runner token, redact for everyone else. Both transforms
+ * mutate the fresh store unmarshal, never the stored row.
+ *
+ * With the authorizeExecutionContextRead capability composed (C4, gate
+ * ruling Q1), the provider owns the ENTIRE trust decision — its lane set
+ * and scope bindings (the cloud's session/workflow/connect rules) replace
+ * the OSS execution-scoped check below. Redaction-as-success stays the
+ * contract on every arm.
+ */
+export async function resolveValuesForCaller(
+  deps: ResolveValuesDeps,
+  ctx: HandlerContext,
+  ec: ExecutionContext,
+): Promise<void> {
+  if (await runnerMayDecrypt(deps, ctx, ec)) {
+    await decryptSecretValues(deps, ec);
+    return;
+  }
+  redactExecutionContextSecrets(ec);
+}
+
+/**
+ * The trust decision: the composed capability when present, the OSS
+ * execution-scoped verify otherwise. A capability that THROWS is a bug in
+ * the composition, not a credential failure — it still falls closed to
+ * redaction, WARN-logged, because a read that would have redacted must
+ * never start failing outright on a policy fault (the
+ * redaction-as-success contract).
+ */
+async function runnerMayDecrypt(
+  deps: ResolveValuesDeps,
+  ctx: HandlerContext,
+  ec: ExecutionContext,
+): Promise<boolean> {
+  const authorizeRead =
+    deps.runnerAuthService.authorizeExecutionContextRead?.bind(
+      deps.runnerAuthService,
+    );
+  if (authorizeRead !== undefined) {
+    const token = bearerToken(ctx);
+    if (token === "") {
+      return false;
+    }
+    try {
+      return await authorizeRead(token, ec.spec?.executionId ?? "");
+    } catch (error) {
+      deps.logger.warn(
+        "ExecutionContext read authorization failed — redacting secrets",
+        { error: error instanceof Error ? error.message : String(error) },
+      );
+      return false;
+    }
+  }
+
+  const executionId = verifyRunnerToken(deps, ctx, ec);
+  if (executionId !== undefined) {
+    deps.logger.debug(
+      "Scope-bound runner token presented - decrypting execution context secrets",
+      { executionId },
+    );
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Go verifyRunnerToken: the execution id the token is bound to when the
+ * caller presented a valid runner token bound to exactly this execution
+ * context; undefined otherwise. Every failure mode answers undefined —
+ * the caller falls closed to redaction — with the mismatch case
+ * WARN-logged because a runner reading across executions indicates a bug,
+ * while an absent header is just an ordinary user-shaped read. A keyless
+ * provider rejects every token (verify throws), the TS shape of Go's
+ * nil-service arm: without a key no token can be genuine. This lane
+ * accepts exactly the execution_scoped credential lane — the caller-side
+ * trust statement the provider contract requires.
+ */
+function verifyRunnerToken(
+  deps: ResolveValuesDeps,
+  ctx: HandlerContext,
+  ec: ExecutionContext,
+): string | undefined {
+  const token = bearerToken(ctx);
+  if (token === "") {
+    return undefined;
+  }
+
+  let tokenExecutionId: string;
+  try {
+    tokenExecutionId = deps.runnerAuthService.verify(
+      TOKEN_TYPE_EXECUTION_SCOPED,
+      token,
+    );
+  } catch {
+    deps.logger.debug(
+      "Presented runner token failed verification - redacting execution context secrets",
+    );
+    return undefined;
+  }
+
+  if (tokenExecutionId !== (ec.spec?.executionId ?? "")) {
+    deps.logger.warn(
+      "Runner token is not scope-bound to this execution context - redacting secrets",
+      {
+        tokenExecutionId,
+        executionId: ec.spec?.executionId ?? "",
+      },
+    );
+    return undefined;
+  }
+
+  return tokenExecutionId;
+}
+
+/**
+ * The Bearer credential from the request's authorization header; empty
+ * when absent or differently shaped. The parsing shape (Go's exact
+ * bearerToken semantics, including the repeated-header first-segment
+ * rule) is the ONE shared definition in the identity chassis — promoted
+ * there when the verifier chain became its second consumer (O2).
+ */
+function bearerToken(ctx: HandlerContext): string {
+  return parseBearerToken(ctx.requestHeader.get("authorization") ?? "");
+}
+
+/**
+ * Go decryptSecretValues: walks spec.data and decrypts every encrypted
+ * is_secret value in place, per the doctrine documented on the module
+ * header.
+ */
+async function decryptSecretValues(
+  deps: ResolveValuesDeps,
+  ec: ExecutionContext,
+): Promise<void> {
+  const executionId = ec.spec?.executionId ?? "";
+  const data = ec.spec?.data ?? {};
+  // One value at a time, deliberately NOT the batch verb: decryptAll
+  // fails as a whole, and this lane's contract is per-key skip for
+  // value-scoped failures.
+  for (const [key, value] of Object.entries(data)) {
+    if (!value.isSecret || !deps.secretService.isEncrypted(value.value)) {
+      continue;
+    }
+
+    try {
+      value.value = await deps.secretService.decrypt(value.value);
+    } catch (error) {
+      if (error instanceof EncryptionUnavailableError) {
+        throw internalError(
+          error,
+          encryptionKeyMissingMessage(executionId, key),
+        );
+      }
+      deps.logger.warn(
+        "Undecryptable ciphertext in execution context — dropping this value from the runner read",
+        {
+          key,
+          executionId,
+          error: error instanceof Error ? error.message : String(error),
+        },
+      );
+      delete data[key];
+    }
+  }
+}

package/src/domain/executioncontext/search-extractor.ts

@@ -0,0 +1,61 @@
+/**
+ * ExecutionContext search extractor — ports pkg/query/search/extractor/
+ * execution_context_extractor.go (both sides: the #4 index side, the #14
+ * query side). Execution contexts have no description field, so the
+ * summary is empty everywhere — and secret DATA is deliberately never
+ * indexed nor projected: only name, tags, org, and visibility reach the
+ * search index and the SearchResult.
+ */
+import type { Message } from "@bufbuild/protobuf";
+
+import { ExecutionContextSchema } from "@stigmer/protos/ai/stigmer/agentic/executioncontext/v1/api_pb";
+import type { ExecutionContext } from "@stigmer/protos/ai/stigmer/agentic/executioncontext/v1/api_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
+import type { SearchResult } from "@stigmer/protos/ai/stigmer/search/v1/io_pb";
+
+import type { SearchIndexEntry } from "../../store/interface.js";
+import { buildSearchResult } from "../../query/search/extractor.js";
+import type { SearchableExtractor } from "../../query/search/extractor.js";
+
+export const executionContextSearchExtractor: SearchableExtractor = {
+  kind: ApiResourceKind.execution_context,
+  schema: ExecutionContextSchema,
+
+  getSearchSummary(): string {
+    // Go ExecutionContextExtractor.GetSearchSummary: always "".
+    return "";
+  },
+
+  toSearchResult(resource: Message, score: number): SearchResult | undefined {
+    const ec = resource as unknown as ExecutionContext;
+    return buildSearchResult({
+      kind: ApiResourceKind.execution_context,
+      metadata: ec.metadata,
+      summary: "",
+      score,
+      createdAt: ec.status?.audit?.specAudit?.createdAt,
+      updatedAt: ec.status?.audit?.specAudit?.updatedAt,
+    });
+  },
+
+  getSearchIndexEntry(resource: Message): SearchIndexEntry | undefined {
+    const ec = resource as unknown as ExecutionContext;
+    const metadata = ec.metadata;
+    if (metadata === undefined) {
+      return undefined;
+    }
+    return {
+      name: metadata.name,
+      // No description field on the spec; Go's GetSearchSummary returns "".
+      description: "",
+      // Tags join space-separated — the index entry carries one tags
+      // string (Go extractor.JoinTags).
+      tags: metadata.tags.join(" "),
+      org: metadata.org,
+      // The enum NAME string, exactly Go's visibility.String().
+      visibility: ApiResourceVisibility[metadata.visibility] ?? "",
+      createdAt: Number(ec.status?.audit?.specAudit?.createdAt?.seconds ?? 0n),
+    };
+  },
+};

package/src/domain/executioncontext/steps.ts

@@ -0,0 +1,283 @@
+/**
+ * ExecutionContext domain steps — port the domain-local steps of
+ * pkg/domain/executioncontext/controller/ (the write-boundary ciphertext
+ * guard, the encrypt-at-rest step, and the execution_id loader).
+ *
+ * The ordering contract these steps embody (oss#535, the EC flavor of the
+ * environment domain's "sentinels → encrypt" doc):
+ *   1. RejectCiphertextShapedValues runs BEFORE EncryptSecretValues.
+ *      ExecutionContext is create-only with NO redaction round-trip
+ *      (unlike Environment, whose PreserveRedactedSecrets restores
+ *      ***REDACTED*** markers on update), so this guard is the WHOLE
+ *      write boundary: every legitimate creator — the agent/workflow
+ *      builders, the MCP connect handler, an SDK caller — supplies
+ *      plaintext, and nothing with an enc:v<N>: prefix reaches the store
+ *      except server-produced ciphertext. That is what keeps the decrypt
+ *      lane safe from forged or replayed blobs.
+ *   2. Redaction (redact.ts) runs AFTER Persist, outside the pipeline.
+ *
+ * Proven by executioncontext.conformance.test.ts
+ * (CONFORMANCE_TARGET=local) and __tests__/executioncontext.test.ts.
+ */
+import { ExecutionContextSchema } from "@stigmer/protos/ai/stigmer/agentic/executioncontext/v1/api_pb";
+import type { ExecutionContext } from "@stigmer/protos/ai/stigmer/agentic/executioncontext/v1/api_pb";
+import type { ExecutionContextExecutionIdInput } from "@stigmer/protos/ai/stigmer/agentic/executioncontext/v1/io_pb";
+import type { ExecutionValue } from "@stigmer/protos/ai/stigmer/agentic/executioncontext/v1/spec_pb";
+import type { ExecutionContextQueryController } from "@stigmer/protos/ai/stigmer/agentic/executioncontext/v1/query_pb";
+
+import { Code, ConnectError } from "@connectrpc/connect";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { IamPermission } from "@stigmer/protos/ai/stigmer/iam/v1/enum_pb";
+
+import type { Logger } from "../../boot/logger.js";
+import { isCiphertextShaped } from "../../encryption/encryption.js";
+import type { SecretService } from "../../encryption/encryption.js";
+import { EncryptionScope } from "../../encryption/encryption.js";
+import type { Authorizer, AuthzDecision } from "../../extensions/authorizer.js";
+import {
+  internalError,
+  invalidArgumentError,
+  notFoundError,
+} from "../../pipeline/errors.js";
+import type { PipelineStep } from "../../pipeline/pipeline.js";
+import type { RequestContext } from "../../pipeline/request-context.js";
+import { TARGET_RESOURCE_KEY } from "../../pipeline/steps/load-target.js";
+import { ResourceNotFoundError } from "../../store/interface.js";
+import type { Store } from "../../store/interface.js";
+import {
+  ENCRYPT_BATCH_FAILURE_MESSAGE,
+  ciphertextShapedMessage,
+} from "./constants.js";
+
+/**
+ * RejectCiphertextShapedValues — Go rejectCiphertextShapedStep: refuses
+ * client-supplied values that look like stored ciphertext (the enc:v<N>:
+ * prefix family, ANY version — an unknown future version fails closed) —
+ * the EC flavor of the oss#395 / cloud#229 write-boundary guard. Without
+ * it, the encrypt step's idempotent pass-through would let a caller
+ * smuggle a forged or replayed ciphertext blob into the store, where the
+ * runner lane would later try to decrypt it.
+ *
+ * Checks ALL of spec.data — secret and non-secret alike, exactly as Go
+ * does: the prefix is server-reserved regardless of the is_secret flag.
+ * Reads the immutable input (Go ctx.Input()), the request as the client
+ * sent it.
+ */
+export function newRejectCiphertextShapedStep(): PipelineStep<
+  typeof ExecutionContextSchema
+> {
+  return {
+    name: "RejectCiphertextShapedValues",
+    execute(ctx: RequestContext<typeof ExecutionContextSchema>): void {
+      const data = ctx.input.spec?.data ?? {};
+      for (const [key, value] of Object.entries(data)) {
+        if (isCiphertextShaped(value.value)) {
+          throw invalidArgumentError(ciphertextShapedMessage(key));
+        }
+      }
+    },
+  };
+}
+
+/**
+ * EncryptSecretValues — Go encryptSecretValuesStep: encrypts every
+ * non-empty is_secret value in spec.data before persistence — the EC twin
+ * of the environment domain's step of the same name, closing the at-rest
+ * half of oss#535 (the merged EC — decrypted environment secrets,
+ * runtime_env overrides, injected OAuth tokens — rested plaintext for
+ * each run's duration, the same backup-exposure class oss#405 closed for
+ * environments).
+ *
+ * Runs after RejectCiphertextShapedValues, so every secret value reaching
+ * it is client plaintext; encrypt's idempotent pass-through is therefore
+ * never exercised by design, but keeps a double application harmless.
+ *
+ * Keyless mode: values pass through plaintext with one WARN per request,
+ * emitted only when a non-empty secret would actually rest plaintext (the
+ * oss#394 convention). Non-secret values are never touched: the read
+ * paths gate decryption on is_secret, so encrypting a non-secret value
+ * would strand it as unreadable ciphertext.
+ *
+ * Seals as ONE batch through the v2-capped verb — the Java service's
+ * encryptAllV2 lane (vault project DD-005): EC values are ephemeral, on
+ * the runner's latency-budgeted read path, so a vault-backed write codec
+ * must spend one batched KEK round trip here, never one per value, and a
+ * future v3 write flip must not drag these unlocatable rows with it.
+ * Under the v1-only OSS default the batch is behaviorally identical to
+ * the per-value loop it replaced, except that an encrypt failure (never
+ * observed for local AES-GCM) reports without the failing key name —
+ * disclosed with the codec seam (20260830.04 Stage 1).
+ */
+export function newEncryptSecretValuesStep(
+  secretService: SecretService,
+  logger: Logger,
+): PipelineStep<typeof ExecutionContextSchema> {
+  return {
+    name: "EncryptSecretValues",
+    async execute(
+      ctx: RequestContext<typeof ExecutionContextSchema>,
+    ): Promise<void> {
+      const ec = ctx.newState;
+      const data = ec.spec?.data;
+      if (data === undefined || Object.keys(data).length === 0) {
+        return;
+      }
+
+      if (!secretService.isEnabled()) {
+        if (hasNonEmptySecret(data)) {
+          logger.warn(
+            "Encryption disabled: execution context secret values will be stored in plaintext",
+            { executionId: ec.spec?.executionId ?? "" },
+          );
+        }
+        return;
+      }
+
+      const toSeal = new Map<string, string>();
+      for (const [key, value] of Object.entries(data)) {
+        if (!value.isSecret || value.value === "") {
+          continue;
+        }
+        toSeal.set(key, value.value);
+      }
+      if (toSeal.size === 0) {
+        return;
+      }
+
+      let sealed: Map<string, string>;
+      try {
+        sealed = await secretService.encryptAllAtMostV2(
+          toSeal,
+          EncryptionScope.forOrganization(ec.metadata?.org ?? ""),
+        );
+      } catch (error) {
+        throw internalError(error, ENCRYPT_BATCH_FAILURE_MESSAGE);
+      }
+      for (const [key, value] of Object.entries(data)) {
+        const sealedValue = sealed.get(key);
+        if (sealedValue !== undefined) {
+          value.value = sealedValue;
+        }
+      }
+    },
+  };
+}
+
+/** Whether any entry would have been encrypted — keeps the WARN honest. */
+function hasNonEmptySecret(data: Record<string, ExecutionValue>): boolean {
+  return Object.values(data).some((v) => v.isSecret && v.value !== "");
+}
+
+type GetByExecutionIdDesc =
+  typeof ExecutionContextQueryController.method.getByExecutionId.input;
+
+/**
+ * LoadByExecutionId — Go loadByExecutionIdStep: loads an ExecutionContext
+ * by querying the spec.executionId FIELD (protobuf JSON naming), not the
+ * resource id — the runner's lookup key is the parent execution's id.
+ * findByField is a full scan of the kind with first-match semantics, the
+ * Go-parity behavior the store interface documents.
+ *
+ * The empty-input guard is unreachable behind ValidateProto (min_len 1 on
+ * execution_id) but ports Go's in-step defense verbatim so the chains
+ * correspond step-for-step.
+ */
+export function newLoadByExecutionIdStep(
+  store: Store,
+): PipelineStep<GetByExecutionIdDesc> {
+  return {
+    name: "LoadByExecutionId",
+    async execute(ctx: RequestContext<GetByExecutionIdDesc>): Promise<void> {
+      const input: ExecutionContextExecutionIdInput = ctx.input;
+      if (input.executionId === "") {
+        throw invalidArgumentError("execution_id is required");
+      }
+
+      let executionContext: ExecutionContext;
+      try {
+        executionContext = await store.findByField(
+          ctx.apiResourceKind,
+          "spec.executionId",
+          input.executionId,
+          ExecutionContextSchema,
+        );
+      } catch (error) {
+        if (error instanceof ResourceNotFoundError) {
+          throw notFoundError(
+            "execution_context",
+            `execution_id=${input.executionId}`,
+          );
+        }
+        throw internalError(error, "failed to query execution context");
+      }
+
+      ctx.set(TARGET_RESOURCE_KEY, executionContext);
+    },
+  };
+}
+
+/**
+ * AuthorizeCreate — the Java ExecutionContextCreateHandler.AuthorizeCreate
+ * port (stigmer-cloud#297; C2 Stage 3D): the create RPC skips the
+ * declarative position-1 check (in-process creators — the agent/workflow
+ * execution machinery — already authorized the run against its
+ * session-or-org and act as the machine account), so EXTERNAL callers are
+ * gated here instead: they must hold can_create_execution_in on
+ * metadata.org — the same permission that gates creating an execution in
+ * the org, so members and org guests pass and an outsider refuses.
+ * Ordered before the duplicate check so an unauthorized caller learns
+ * nothing about which execution ids exist.
+ *
+ * OSS byte-identity: the permissive authorizer allows every check, so the
+ * single-user posture is unchanged (the rosters prove it).
+ */
+export function newAuthorizeExecutionContextCreateStep(
+  authorizer: Authorizer,
+): PipelineStep<typeof ExecutionContextSchema> {
+  return {
+    name: "AuthorizeCreate",
+    async execute(
+      ctx: RequestContext<typeof ExecutionContextSchema>,
+    ): Promise<void> {
+      const caller = ctx.callerIdentity;
+      if (caller.callerClass === "internal" || caller.origin === "in-process") {
+        return; // authorized upstream — the Java in-process trust arm
+      }
+      let decision: AuthzDecision;
+      try {
+        decision = await authorizer.authorize(caller, {
+          permission: IamPermission.can_create_execution_in,
+          resourceKind: ApiResourceKind.organization,
+          resourceId: ctx.newState.metadata?.org ?? "",
+        });
+      } catch (error) {
+        throw internalError(
+          error instanceof Error ? error : new Error(String(error)),
+          "execution-context create authorization could not be completed",
+        );
+      }
+      switch (decision.kind) {
+        case "allow":
+          return;
+        case "deny":
+        case "not-found":
+          throw new ConnectError(
+            "unauthorized to create execution context in this organization",
+            Code.PermissionDenied,
+          );
+        case "unavailable":
+          throw internalError(
+            decision.cause,
+            "execution-context create authorization could not be completed",
+          );
+        default: {
+          const exhaustive: never = decision;
+          throw internalError(
+            new Error(`unknown decision ${JSON.stringify(exhaustive)}`),
+            "execution-context create authorization could not be completed",
+          );
+        }
+      }
+    },
+  };
+}

package/src/domain/executioncontext/temporal/delete-execution-context.ts

@@ -0,0 +1,96 @@
+/**
+ * DeleteExecutionContext activity seam — ports
+ * pkg/domain/executioncontext/temporal/activities/delete_execution_context.go.
+ *
+ * The ExecutionContext is an ephemeral resource containing the
+ * fully-merged environment (environment_refs values overridden by
+ * runtime_env, filtered to the blueprint's declared env keys), including
+ * secrets. It must be cleaned up when the execution finishes so sensitive
+ * data does not persist beyond the execution lifetime.
+ *
+ * A SEAM, deliberately unregistered: this module has no Temporal SDK
+ * dependency — it is the plain store-direct function the agent-execution
+ * and workflow-execution workers (D4 #18/#21) will register as a local
+ * activity under DELETE_EXECUTION_CONTEXT_ACTIVITY_NAME, shared by both
+ * workflows exactly as in Go.
+ *
+ * Behavior (Go parity):
+ *   - Idempotent: no-op if the ExecutionContext does not exist.
+ *   - Best-effort: logs failures but never throws — cleanup failure must
+ *     not affect the workflow outcome. A failed delete leaves the row in
+ *     place with its secret values still encrypted at rest (oss#535);
+ *     nothing retries it later, so the WARN is the operator's signal.
+ *   - Security-aware: logs the variable count, never names or values.
+ */
+import { ExecutionContextSchema } from "@stigmer/protos/ai/stigmer/agentic/executioncontext/v1/api_pb";
+import type { ExecutionContext } from "@stigmer/protos/ai/stigmer/agentic/executioncontext/v1/api_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import type { Logger } from "../../../boot/logger.js";
+import { ResourceNotFoundError } from "../../../store/interface.js";
+import type { Store } from "../../../store/interface.js";
+
+/** The activity name for worker registration — Go's constant, byte-pinned. */
+export const DELETE_EXECUTION_CONTEXT_ACTIVITY_NAME = "DeleteExecutionContext";
+
+/**
+ * Finds and deletes the ExecutionContext for the given execution ID
+ * (an AgentExecution or WorkflowExecution id — the lookup uses the
+ * spec.executionId field).
+ */
+export async function deleteExecutionContextForExecution(
+  store: Store,
+  logger: Logger,
+  executionId: string,
+): Promise<void> {
+  logger.debug("Cleaning up ExecutionContext for execution", { executionId });
+
+  let ec: ExecutionContext;
+  try {
+    ec = await store.findByField(
+      ApiResourceKind.execution_context,
+      "spec.executionId",
+      executionId,
+      ExecutionContextSchema,
+    );
+  } catch (error) {
+    if (error instanceof ResourceNotFoundError) {
+      logger.debug(
+        "No ExecutionContext found for execution -- nothing to clean up",
+        { executionId },
+      );
+      return;
+    }
+    logger.warn(
+      "Failed to query ExecutionContext -- leaving cleanup to the operator",
+      {
+        executionId,
+        error: error instanceof Error ? error.message : String(error),
+      },
+    );
+    return;
+  }
+
+  const contextId = ec.metadata?.id ?? "";
+  const dataCount = Object.keys(ec.spec?.data ?? {}).length;
+
+  try {
+    await store.deleteResource(ApiResourceKind.execution_context, contextId);
+  } catch (error) {
+    logger.warn(
+      "Failed to delete ExecutionContext -- leaving cleanup to the operator",
+      {
+        executionId,
+        contextId,
+        error: error instanceof Error ? error.message : String(error),
+      },
+    );
+    return;
+  }
+
+  logger.info("Deleted ExecutionContext for execution", {
+    executionId,
+    contextId,
+    variables: dataCount,
+  });
+}