@stigmer/server 3.14.0-dev.20260910084630

package/dist/domain/workflowexecution/create-execution-context-step.js

@@ -0,0 +1,141 @@
+/**
+ * CreateExecutionContext — ports create_execution_context_step.go: builds
+ * and persists the ExecutionContext carrying the fully-merged environment
+ * for the run, then strips spec.runtime_env so secrets never reach the
+ * persisted execution or Temporal history.
+ *
+ * Resolution chain: execution.spec.workflow_instance_id (always set by
+ * CreateDefaultInstanceIfNeeded) → instance.environment_refs resolved
+ * through the environment RuntimeResolutionService (decrypted — the RPC
+ * surface redacts, oss#405) → envmerge with spec.runtime_env as the top
+ * layer → least-privilege filter against the workflow's env declarations
+ * (undeclared keys warn + drop; empty declarations pass everything for
+ * backward compatibility) → required-key validation (warn-only) →
+ * ExecutionContext create through the in-process client.
+ *
+ * Go skips the whole step when its late-injected deps are nil; the TS
+ * composition root wires them unconditionally, so that arm is
+ * structurally unreachable here and deliberately not modeled (the
+ * loud-boot doctrine: a missing dependency is a wiring bug, not a mode).
+ *
+ * The recover pipeline's RecreateExecutionContext twin lives in
+ * lifecycle.ts — its failure posture differs (degrade gracefully).
+ */
+import { create } from "@bufbuild/protobuf";
+import { ConnectError } from "@connectrpc/connect";
+import { ExecutionContextSchema } from "@stigmer/protos/ai/stigmer/agentic/executioncontext/v1/api_pb";
+import { WorkflowSchema } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/api_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { filterByDeclaredKeys, mergeEnvironmentLayers, validateRequiredKeys, } from "../../envmerge/envmerge.js";
+import { goWrappedStatusError, internalError, } from "../../pipeline/errors.js";
+export function newCreateExecutionContextStep(deps) {
+    return {
+        name: "CreateExecutionContext",
+        async execute(ctx) {
+            const execution = ctx.newState;
+            const executionId = execution.metadata?.id ?? "";
+            const executionOrg = execution.metadata?.org ?? "";
+            // CreateDefaultInstanceIfNeeded always stamps this, user-provided
+            // or auto-resolved.
+            const workflowInstanceId = execution.spec?.workflowInstanceId ?? "";
+            if (workflowInstanceId === "") {
+                throw internalError(new Error("workflow_instance_id not resolved from context or execution spec"), "workflow_instance_id not resolved from context or execution spec");
+            }
+            let instance;
+            try {
+                instance = await deps.workflowInstanceLoader().get(workflowInstanceId);
+            }
+            catch (error) {
+                if (error instanceof ConnectError) {
+                    throw goWrappedStatusError(`load workflow instance ${workflowInstanceId}`, error);
+                }
+                throw internalError(error, `load workflow instance ${workflowInstanceId}`);
+            }
+            const workflowId = instance.spec?.workflowId ?? "";
+            let workflow;
+            try {
+                workflow = await deps.store.getResource(ApiResourceKind.workflow, workflowId, WorkflowSchema);
+            }
+            catch (error) {
+                throw internalError(error, `load workflow ${workflowId}`);
+            }
+            const environments = await resolveEnvironments(deps, instance.spec?.environmentRefs ?? []);
+            const merged = mergeEnvironmentLayers(environments, execution.spec?.runtimeEnv ?? {});
+            // Least-privilege whitelist: workflows only receive declared vars.
+            const workflowEnvDecls = workflow.spec?.env ?? {};
+            const { filtered, excludedKeys } = filterByDeclaredKeys(merged, workflowEnvDecls);
+            if (excludedKeys.length > 0) {
+                deps.logger.warn("Filtered env vars not declared in workflow env", {
+                    executionId,
+                    workflowId,
+                    excludedKeys,
+                });
+            }
+            const missingRequired = validateRequiredKeys(filtered, workflowEnvDecls);
+            if (missingRequired.length > 0) {
+                deps.logger.warn("Required env vars missing after environment merge — execution may fail", { executionId, workflowId, missingRequired });
+            }
+            const executionContext = create(ExecutionContextSchema, {
+                apiVersion: "agentic.stigmer.ai/v1",
+                kind: "ExecutionContext",
+                metadata: {
+                    name: `exec-ctx-${executionId}`,
+                    org: executionOrg,
+                },
+                spec: {
+                    executionId,
+                    data: Object.fromEntries(filtered),
+                },
+            });
+            try {
+                const created = await deps
+                    .executionContextCreator()
+                    .create(executionContext);
+                deps.logger.info("Successfully created execution context", {
+                    executionContextId: created.metadata?.id ?? "",
+                    executionId,
+                    dataEntries: filtered.size,
+                });
+            }
+            catch (error) {
+                if (error instanceof ConnectError) {
+                    throw goWrappedStatusError(`create execution context for ${executionId}`, error);
+                }
+                throw internalError(error, `create execution context for ${executionId}`);
+            }
+            // runtime_env is a transient creation-time input, now materialized
+            // in the ExecutionContext; clearing it keeps secrets out of the
+            // persisted execution and Temporal history.
+            if (execution.spec !== undefined &&
+                Object.keys(execution.spec.runtimeEnv).length > 0) {
+                execution.spec.runtimeEnv = {};
+            }
+        },
+    };
+}
+/**
+ * Fetches each referenced Environment in order through the runtime
+ * resolution service (decrypted values; the RPC surface redacts,
+ * oss#405). A failed ref fails the create — Go wraps with the ref
+ * coordinates.
+ */
+async function resolveEnvironments(deps, refs) {
+    if (refs.length === 0) {
+        return [];
+    }
+    const environments = [];
+    for (const ref of refs) {
+        try {
+            environments.push(await deps.environmentResolution.resolveByReference(ref));
+        }
+        catch (error) {
+            const prefix = `resolve environment ref (org=${ref.org}, slug=${ref.slug})`;
+            if (error instanceof ConnectError) {
+                throw goWrappedStatusError(prefix, error);
+            }
+            throw internalError(error, prefix);
+        }
+    }
+    return environments;
+}
+//# sourceMappingURL=create-execution-context-step.js.map

package/dist/domain/workflowexecution/create-execution-context-step.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-execution-context-step.js","sourceRoot":"","sources":["../../../src/domain/workflowexecution/create-execution-context-step.ts"],"names":[],"mappings":"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"}

package/dist/domain/workflowexecution/create-steps.d.ts

@@ -0,0 +1,70 @@
+import type { WorkflowInstance } from "@stigmer/protos/ai/stigmer/agentic/workflowinstance/v1/api_pb";
+import { WorkflowExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
+import type { Logger } from "../../boot/logger.js";
+import type { CallerIdentity } from "../../extensions/identity.js";
+import type { ResourceAuthorizationLifecycle } from "../../extensions/resource-authorization.js";
+import type { PipelineStep } from "../../pipeline/pipeline.js";
+import type { Store } from "../../store/interface.js";
+import type { WorkflowExecutionEngineStateProvider } from "./engine.js";
+type ExecutionDesc = typeof WorkflowExecutionSchema;
+/**
+ * The narrow workflowinstance CREATE edge — as the ORIGINAL caller since
+ * C2 Stage 3 (ruling R5, the Java createAsCaller posture): real owner
+ * attribution for the created instance under an enforcing Authorizer.
+ */
+export interface ExecutionWorkflowInstanceCreator {
+    createAsCaller(instance: WorkflowInstance, caller: CallerIdentity): Promise<WorkflowInstance>;
+}
+export type ExecutionWorkflowInstanceCreatorProvider = () => ExecutionWorkflowInstanceCreator;
+/**
+ * ValidateWorkflowOrInstance — at least one of workflow_id /
+ * workflow_instance_id must be provided. Matches the cloud
+ * WorkflowExecutionCreateHandler. AgentExecution differs: it has a
+ * ResolveDefaultAgent step, so its guard is an unreachable invariant
+ * (Internal), not reachable InvalidArgument validation (issue #196).
+ */
+export declare function newValidateWorkflowOrInstanceStep(): PipelineStep<ExecutionDesc>;
+export interface CreateDefaultInstanceDeps {
+    readonly store: Store;
+    readonly logger: Logger;
+    readonly workflowInstanceCreator: ExecutionWorkflowInstanceCreatorProvider;
+    readonly authorizationLifecycle?: ResourceAuthorizationLifecycle;
+}
+/**
+ * CreateDefaultInstanceIfNeeded — create.go: when only workflow_id is
+ * provided, resolve (or provision) the workflow's default instance:
+ *
+ *   1. load the workflow (NotFound if missing);
+ *   2. use status.default_instance_id when set;
+ *   3. else look the instance up by its deterministic slug — the
+ *      self-heal for a past run where the instance was created but the
+ *      workflow status write failed (prevents duplicate-slug errors);
+ *   4. else create it via the in-process client (CreateAsSystem) and
+ *      write default_instance_id back onto the workflow.
+ *
+ * Every path stamps the resolved id onto execution.spec.
+ * workflow_instance_id, which downstream steps (EC creation, workflow
+ * start) read.
+ */
+export declare function newCreateDefaultInstanceIfNeededStep(deps: CreateDefaultInstanceDeps): PipelineStep<ExecutionDesc>;
+/**
+ * SetInitialPhase — PENDING before the Temporal workflow starts, so the
+ * frontend shows a thinking indicator immediately.
+ */
+export declare function newSetInitialPhaseStep(): PipelineStep<ExecutionDesc>;
+export interface StartWorkflowDeps {
+    readonly store: Store;
+    readonly logger: Logger;
+    readonly engineState: WorkflowExecutionEngineStateProvider;
+}
+/**
+ * StartWorkflow — create.go startWorkflowStep: runs AFTER persist. Engine
+ * availability was guaranteed by the step-4 gate, so a failure here is a
+ * live/transient Temporal error: the execution is marked FAILED with the
+ * error text and persisted (recoverable via Recover), then the RPC
+ * answers Internal. Dispatch-queue resolution lives inside the engine
+ * (#21), fed by spec.execution_target.
+ */
+export declare function newStartWorkflowStep(deps: StartWorkflowDeps): PipelineStep<ExecutionDesc>;
+export {};
+//# sourceMappingURL=create-steps.d.ts.map

package/dist/domain/workflowexecution/create-steps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-steps.d.ts","sourceRoot":"","sources":["../../../src/domain/workflowexecution/create-steps.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,+DAA+D,CAAC;AAKtG,OAAO,EACL,uBAAuB,EAExB,MAAM,gEAAgE,CAAC;AAIxE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,4CAA4C,CAAC;AAQjG,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC/D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAC;AAMtD,OAAO,KAAK,EAAE,oCAAoC,EAAE,MAAM,aAAa,CAAC;AAExE,KAAK,aAAa,GAAG,OAAO,uBAAuB,CAAC;AAEpD;;;;GAIG;AACH,MAAM,WAAW,gCAAgC;IAC/C,cAAc,CACZ,QAAQ,EAAE,gBAAgB,EAC1B,MAAM,EAAE,cAAc,GACrB,OAAO,CAAC,gBAAgB,CAAC,CAAC;CAC9B;AACD,MAAM,MAAM,wCAAwC,GAClD,MAAM,gCAAgC,CAAC;AAEzC;;;;;;GAMG;AACH,wBAAgB,iCAAiC,IAAI,YAAY,CAAC,aAAa,CAAC,CAe/E;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,uBAAuB,EAAE,wCAAwC,CAAC;IAC3E,QAAQ,CAAC,sBAAsB,CAAC,EAAE,8BAA8B,CAAC;CAClE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oCAAoC,CAClD,IAAI,EAAE,yBAAyB,GAC9B,YAAY,CAAC,aAAa,CAAC,CAgG7B;AAoED;;;GAGG;AACH,wBAAgB,sBAAsB,IAAI,YAAY,CAAC,aAAa,CAAC,CAWpE;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,oCAAoC,CAAC;CAC5D;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,iBAAiB,GACtB,YAAY,CAAC,aAAa,CAAC,CAgE7B"}

package/dist/domain/workflowexecution/create-steps.js

@@ -0,0 +1,254 @@
+/**
+ * Create-pipeline steps — ports create.go's inline steps: the
+ * workflow-or-instance presence validation (the #196 InvalidArgument
+ * contrast to agentexecution's Internal invariant), the self-healing
+ * default-instance resolution, the initial PENDING phase, and the
+ * post-persist Temporal start whose failure marks the execution FAILED
+ * (recoverable via Recover).
+ *
+ * The engine gate itself lives in engine.ts (shared shape with the
+ * sibling domain); its pinned position is step 4 of the create chain.
+ */
+import { create } from "@bufbuild/protobuf";
+import { ConnectError } from "@connectrpc/connect";
+import { WorkflowInstanceSchema } from "@stigmer/protos/ai/stigmer/agentic/workflowinstance/v1/api_pb";
+import { WorkflowSchema } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/api_pb";
+import { WorkflowStatusSchema } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/status_pb";
+import { WorkflowExecutionSchema, WorkflowExecutionStatusSchema, } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
+import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/enum_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { notifyDefaultInstanceLinked } from "../../pipeline/steps/authorization-tuples.js";
+import { goWrappedStatusError, internalError, invalidArgumentError, notFoundError, } from "../../pipeline/errors.js";
+import { fromBinary } from "@bufbuild/protobuf";
+import { defaultWorkflowInstanceSlug } from "../workflowinstance/defaultinstance.js";
+import { buildDefaultWorkflowInstanceRequest } from "../workflowinstance/defaultinstance.js";
+/**
+ * ValidateWorkflowOrInstance — at least one of workflow_id /
+ * workflow_instance_id must be provided. Matches the cloud
+ * WorkflowExecutionCreateHandler. AgentExecution differs: it has a
+ * ResolveDefaultAgent step, so its guard is an unreachable invariant
+ * (Internal), not reachable InvalidArgument validation (issue #196).
+ */
+export function newValidateWorkflowOrInstanceStep() {
+    return {
+        name: "ValidateWorkflowOrInstance",
+        execute(ctx) {
+            const spec = ctx.input.spec;
+            if ((spec?.workflowInstanceId ?? "") === "" &&
+                (spec?.workflowId ?? "") === "") {
+                throw invalidArgumentError("either workflow_id or workflow_instance_id must be provided");
+            }
+        },
+    };
+}
+/**
+ * CreateDefaultInstanceIfNeeded — create.go: when only workflow_id is
+ * provided, resolve (or provision) the workflow's default instance:
+ *
+ *   1. load the workflow (NotFound if missing);
+ *   2. use status.default_instance_id when set;
+ *   3. else look the instance up by its deterministic slug — the
+ *      self-heal for a past run where the instance was created but the
+ *      workflow status write failed (prevents duplicate-slug errors);
+ *   4. else create it via the in-process client (CreateAsSystem) and
+ *      write default_instance_id back onto the workflow.
+ *
+ * Every path stamps the resolved id onto execution.spec.
+ * workflow_instance_id, which downstream steps (EC creation, workflow
+ * start) read.
+ */
+export function newCreateDefaultInstanceIfNeededStep(deps) {
+    return {
+        name: "CreateDefaultInstanceIfNeeded",
+        async execute(ctx) {
+            const input = ctx.input;
+            if ((input.spec?.workflowInstanceId ?? "") !== "") {
+                return;
+            }
+            const workflowId = input.spec?.workflowId ?? "";
+            const execution = ctx.newState;
+            let workflow;
+            try {
+                workflow = await deps.store.getResource(ApiResourceKind.workflow, workflowId, WorkflowSchema);
+            }
+            catch {
+                throw notFoundError("Workflow", workflowId);
+            }
+            const defaultInstanceId = workflow.status?.defaultInstanceId ?? "";
+            if (defaultInstanceId !== "") {
+                setInstanceId(execution, defaultInstanceId);
+                return;
+            }
+            // Self-heal: the instance may exist even though the workflow status
+            // write failed on a previous run.
+            const slug = defaultWorkflowInstanceSlug(workflow.metadata?.slug ?? "");
+            let existingInstance;
+            try {
+                existingInstance = await findInstanceBySlug(deps, slug);
+            }
+            catch (error) {
+                throw internalError(error, "failed to look up existing default instance");
+            }
+            if (existingInstance !== undefined) {
+                const existingId = existingInstance.metadata?.id ?? "";
+                deps.logger.info("Found existing default instance, updating workflow status", { instanceId: existingId, workflowId });
+                await backfillDefaultInstanceId(deps, workflow, workflowId, existingId, "failed to update workflow with existing default instance");
+                setInstanceId(execution, existingId);
+                return;
+            }
+            deps.logger.info("Default instance not found, creating new one", {
+                workflowId,
+            });
+            const instanceRequest = buildDefaultWorkflowInstanceRequest(workflow.metadata);
+            let createdInstance;
+            try {
+                createdInstance = await deps
+                    .workflowInstanceCreator()
+                    .createAsCaller(instanceRequest, ctx.callerIdentity);
+            }
+            catch (error) {
+                if (error instanceof ConnectError) {
+                    // Go wraps the client error with %w — the inner gRPC code
+                    // survives to the wire (oss#852 convention).
+                    throw goWrappedStatusError("failed to create default workflow instance", error);
+                }
+                throw internalError(error, "failed to create default workflow instance");
+            }
+            const createdId = createdInstance.metadata?.id ?? "";
+            await backfillDefaultInstanceId(deps, workflow, workflowId, createdId, "failed to update workflow with default instance");
+            setInstanceId(execution, createdId);
+            deps.logger.info("Successfully created and registered default instance", {
+                instanceId: createdId,
+                workflowId,
+            });
+        },
+    };
+}
+function setInstanceId(execution, instanceId) {
+    if (execution.spec !== undefined) {
+        execution.spec.workflowInstanceId = instanceId;
+    }
+}
+async function backfillDefaultInstanceId(deps, workflow, workflowId, instanceId, failureMessage) {
+    const status = workflow.status ?? create(WorkflowStatusSchema);
+    workflow.status = status;
+    status.defaultInstanceId = instanceId;
+    try {
+        await deps.store.saveResource(ApiResourceKind.workflow, workflowId, WorkflowSchema, workflow);
+    }
+    catch (error) {
+        throw internalError(error, failureMessage);
+    }
+    // The default_of invariant rides the pointer persist (C2 Stage 3).
+    await notifyDefaultInstanceLinked(deps.authorizationLifecycle, {
+        instanceKind: ApiResourceKind.workflow_instance,
+        instanceId,
+        blueprintKind: ApiResourceKind.workflow,
+        blueprintId: workflowId,
+    });
+}
+/**
+ * Go findInstanceBySlug: a full workflow_instance scan matched on
+ * metadata.slug; malformed rows are skipped.
+ */
+async function findInstanceBySlug(deps, slug) {
+    const rows = await deps.store.listResources(ApiResourceKind.workflow_instance);
+    for (const data of rows) {
+        let instance;
+        try {
+            instance = fromBinary(WorkflowInstanceSchema, data);
+        }
+        catch {
+            deps.logger.warn("Failed to unmarshal workflow instance during slug lookup");
+            continue;
+        }
+        if (instance.metadata?.slug === slug) {
+            return instance;
+        }
+    }
+    return undefined;
+}
+/**
+ * SetInitialPhase — PENDING before the Temporal workflow starts, so the
+ * frontend shows a thinking indicator immediately.
+ */
+export function newSetInitialPhaseStep() {
+    return {
+        name: "SetInitialPhase",
+        execute(ctx) {
+            const execution = ctx.newState;
+            if (execution.status === undefined) {
+                execution.status = create(WorkflowExecutionStatusSchema);
+            }
+            execution.status.phase = ExecutionPhase.EXECUTION_PENDING;
+        },
+    };
+}
+/**
+ * StartWorkflow — create.go startWorkflowStep: runs AFTER persist. Engine
+ * availability was guaranteed by the step-4 gate, so a failure here is a
+ * live/transient Temporal error: the execution is marked FAILED with the
+ * error text and persisted (recoverable via Recover), then the RPC
+ * answers Internal. Dispatch-queue resolution lives inside the engine
+ * (#21), fed by spec.execution_target.
+ */
+export function newStartWorkflowStep(deps) {
+    return {
+        name: "StartWorkflow",
+        async execute(ctx) {
+            const execution = ctx.newState;
+            const executionId = execution.metadata?.id ?? "";
+            const engineState = deps.engineState();
+            // Unreachable while the gate holds (the engine cannot flip between
+            // step 4 and here pre-#21); modeled the same way Go's non-nil
+            // assumption is — a loud failure, not a silent skip.
+            let startError;
+            if (!engineState.connected) {
+                startError = new Error("workflow engine disconnected after the create gate");
+            }
+            else {
+                try {
+                    await engineState.engine.startInvokeWorkflow({
+                        executionId,
+                        workflowInstanceId: execution.spec?.workflowInstanceId ?? "",
+                        workflowId: execution.spec?.workflowId ?? "",
+                        orgId: execution.metadata?.org ?? "",
+                        recoveryMode: false,
+                        executionTarget: execution.spec?.executionTarget ?? 0,
+                    });
+                }
+                catch (error) {
+                    startError =
+                        error instanceof Error ? error : new Error(String(error));
+                }
+            }
+            if (startError === undefined) {
+                deps.logger.info("Temporal workflow started successfully", {
+                    executionId,
+                });
+                return;
+            }
+            deps.logger.error("Failed to start Temporal workflow - marking execution as FAILED", { executionId, error: startError.message });
+            if (execution.status === undefined) {
+                execution.status = create(WorkflowExecutionStatusSchema);
+            }
+            execution.status.phase = ExecutionPhase.EXECUTION_FAILED;
+            execution.status.error = `Failed to start Temporal workflow: ${goErrorText(startError)}`;
+            try {
+                await deps.store.saveResource(ApiResourceKind.workflow_execution, executionId, WorkflowExecutionSchema, execution);
+            }
+            catch (persistError) {
+                throw internalError(persistError, "failed to start workflow and failed to update status");
+            }
+            throw internalError(startError, "failed to start workflow");
+        },
+    };
+}
+/**
+ * The %v rendering Go embeds in status.error: a ConnectError renders as
+ * grpc-go wire text via its message; plain errors as their message.
+ */
+function goErrorText(error) {
+    return error.message;
+}
+//# sourceMappingURL=create-steps.js.map

package/dist/domain/workflowexecution/create-steps.js.map

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

package/dist/domain/workflowexecution/engine.d.ts

@@ -0,0 +1,131 @@
+/**
+ * The workflow-execution engine seam — the ONE place this controller
+ * touches Temporal-shaped behavior before sub-project #21 lands the
+ * workflow-execution orchestrator on #18's shared worker infrastructure.
+ *
+ * Go models engine availability as two separately-injected nilable fields
+ * on the controller (workflowCreator for create/sendSignal/taskApproval/
+ * recover-start, temporalClient for the lifecycle signal/cancel/terminate
+ * steps), re-injected by TemporalManager on every reconnect. The TS
+ * guidelines forbid nullable modeling of optional infrastructure, so
+ * availability is an explicit two-variant state instead (the shape the
+ * sibling agentexecution domain ratified); #21's TemporalManager flips the
+ * provider between the variants exactly where Go calls
+ * SetWorkflowCreator/SetTemporalClient.
+ *
+ * Until #21, the composition root wires ENGINE_DISCONNECTED permanently —
+ * byte-identical behavior to the Go server running without Temporal, with
+ * each call site's own pinned posture (constants.ts): create refuses
+ * Unavailable at the gate; the four lifecycle signal steps and recover's
+ * terminate-existing refuse FailedPrecondition "Temporal is not
+ * available"; sendSignal's send step refuses FailedPrecondition "workflow
+ * creator is not available"; submitWorkflowTaskApproval refuses
+ * Unavailable "workflow creator not configured for task '%s'"; recover's
+ * fresh-start refuses FailedPrecondition with the creator-specific copy.
+ *
+ * The connected variant's surface carries exactly the operations THIS
+ * controller consumes. Workflow IDs are built by the DOMAIN (Go builds
+ * them in the controller steps — they are ported byte-pinned constants,
+ * see constants.ts); dispatch-queue resolution (Go
+ * wftemporal.ResolveWorkflowTaskQueue over spec.execution_target) is
+ * temporal-slice code and lands inside #21's implementations, the same
+ * absorption the agentexecution seam ratified.
+ */
+import type { JsonValue } from "@bufbuild/protobuf";
+import type { ExecutionTarget } from "@stigmer/protos/ai/stigmer/agentic/session/v1/enum_pb";
+import type { WorkflowExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
+import type { PipelineStep } from "../../pipeline/pipeline.js";
+/**
+ * The slim workflow-start input (Go wfactivities.
+ * InvokeWorkflowExecutionWorkflowInput): only orchestration coordinates —
+ * the slim-input doctrine keeps secrets out of Temporal history (they were
+ * already consumed into the ExecutionContext). executionTarget feeds
+ * #21's dispatch resolution ("global" → stigmer_runner, "execution" →
+ * wfexec:{id}); the cloud-only CallbackToken/InvokerIdentityAccountID
+ * fields have no OSS producer and are not modeled.
+ */
+export interface StartWorkflowExecutionInput {
+    readonly executionId: string;
+    readonly workflowInstanceId: string;
+    readonly workflowId: string;
+    readonly orgId: string;
+    readonly recoveryMode: boolean;
+    /** spec.execution_target — consumed by dispatch resolution, not Temporal. */
+    readonly executionTarget: ExecutionTarget;
+}
+/**
+ * The engine operations this controller consumes once Temporal is wired.
+ * Implemented by #21; empty by design until then — see the module header.
+ */
+export interface ConnectedWorkflowExecutionEngine {
+    /**
+     * Starts the orchestrator workflow (Go workflowCreator.Create after
+     * ResolveWorkflowTaskQueue). Used by create's StartWorkflow step and
+     * recover's StartFreshWorkflow step.
+     */
+    startInvokeWorkflow(input: StartWorkflowExecutionInput): Promise<void>;
+    /**
+     * SignalWithStart against the orchestrator (Go
+     * workflowCreator.SignalWithStart) — race-proof for PENDING executions
+     * whose orchestrator has not started yet. Used by sendSignal and
+     * submitWorkflowTaskApproval, always on the relaySignal channel.
+     */
+    signalWithStart(input: StartWorkflowExecutionInput, signalName: string, payload: JsonValue): Promise<void>;
+    /**
+     * Raw signal to a workflow ID (Go temporalClient.SignalWorkflow with
+     * empty run ID = latest run). Used by the pause/resume lifecycle steps
+     * against the orchestrator ID. Throws EngineWorkflowNotFoundError when
+     * the workflow no longer exists — the steps treat that as
+     * warn-and-proceed (the local state update still applies).
+     */
+    signalWorkflow(workflowId: string, signalName: string, payload: JsonValue | undefined): Promise<void>;
+    /**
+     * Cancels a workflow by ID (Go temporalClient.CancelWorkflow, empty run
+     * ID). EngineWorkflowNotFoundError → warn-and-proceed.
+     */
+    cancelWorkflow(workflowId: string): Promise<void>;
+    /**
+     * Terminates a workflow by ID (Go temporalClient.TerminateWorkflow,
+     * empty run ID). EngineWorkflowNotFoundError → warn-and-proceed (the
+     * recover path treats NOT_FOUND on either tree member as success).
+     */
+    terminateWorkflow(workflowId: string, reason: string): Promise<void>;
+}
+/**
+ * The engine's "workflow not found" sentinel (Go *serviceerror.NotFound
+ * from the Temporal client). #21's implementation maps Temporal's
+ * not-found onto it; tests construct it directly.
+ */
+export declare class EngineWorkflowNotFoundError extends Error {
+    constructor(workflowId: string);
+}
+/** Engine availability as an explicit modeled state (guidelines §4). */
+export type WorkflowExecutionEngineState = {
+    readonly connected: true;
+    readonly engine: ConnectedWorkflowExecutionEngine;
+} | {
+    readonly connected: false;
+};
+/**
+ * The permanent pre-#21 state: no Temporal behind this server. A frozen
+ * singleton so identity comparisons in tests stay meaningful.
+ */
+export declare const ENGINE_DISCONNECTED: WorkflowExecutionEngineState;
+/**
+ * A provider rather than a value: #21's TemporalManager re-injects on
+ * every reconnect (Go's SetWorkflowCreator/SetTemporalClient), so
+ * consumers must observe the CURRENT state at request time, never a
+ * boot-time snapshot.
+ */
+export type WorkflowExecutionEngineStateProvider = () => WorkflowExecutionEngineState;
+/**
+ * EnsureEngineAvailable — create.go ensureEngineAvailableStep: rejects the
+ * create fast — before any persistence or side effect — when the engine is
+ * not connected. Pinned position: step 4, after ValidateWorkflowOrInstance
+ * (a malformed request still answers InvalidArgument first) and before
+ * CreateDefaultInstanceIfNeeded (a down engine orphans nothing — no
+ * default instance, no ExecutionContext, no execution record). Go's unit
+ * test pins the precedence: engine-unavailable beats workflow lookup.
+ */
+export declare function newEnsureEngineAvailableStep(engineState: WorkflowExecutionEngineStateProvider): PipelineStep<typeof WorkflowExecutionSchema>;
+//# sourceMappingURL=engine.d.ts.map

package/dist/domain/workflowexecution/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../../src/domain/workflowexecution/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uDAAuD,CAAC;AAC7F,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gEAAgE,CAAC;AAG9G,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAK/D;;;;;;;;GAQG;AACH,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,6EAA6E;IAC7E,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAC;CAC3C;AAED;;;GAGG;AACH,MAAM,WAAW,gCAAgC;IAC/C;;;;OAIG;IACH,mBAAmB,CAAC,KAAK,EAAE,2BAA2B,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvE;;;;;OAKG;IACH,eAAe,CACb,KAAK,EAAE,2BAA2B,EAClC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,SAAS,GACjB,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB;;;;;;OAMG;IACH,cAAc,CACZ,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,SAAS,GAAG,SAAS,GAC7B,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB;;;OAGG;IACH,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAElD;;;;OAIG;IACH,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACtE;AAED;;;;GAIG;AACH,qBAAa,2BAA4B,SAAQ,KAAK;gBACxC,UAAU,EAAE,MAAM;CAI/B;AAED,wEAAwE;AACxE,MAAM,MAAM,4BAA4B,GACpC;IACE,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,gCAAgC,CAAC;CACnD,GACD;IAAE,QAAQ,CAAC,SAAS,EAAE,KAAK,CAAA;CAAE,CAAC;AAElC;;;GAGG;AACH,eAAO,MAAM,mBAAmB,EAAE,4BACG,CAAC;AAEtC;;;;;GAKG;AACH,MAAM,MAAM,oCAAoC,GAC9C,MAAM,4BAA4B,CAAC;AAErC;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAC1C,WAAW,EAAE,oCAAoC,GAChD,YAAY,CAAC,OAAO,uBAAuB,CAAC,CAS9C"}