@stigmer/server 3.21.0 → 3.22.1-dev.20260922095755

package/src/domain/workflow/controller.ts

@@ -45,7 +45,6 @@ import {
   ApiResourceKind,
   ApiResourceKindSchema,
 } 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 {
   ApiResourceReference,
   UpdateVisibilityInput,
@@ -71,14 +70,14 @@ import { callerIdentityOf } from "../../pipeline/interceptors/auth.js";
 import { RequestContext } from "../../pipeline/request-context.js";
 import {
   authorizeDirect,
-  authorizeResolvedResource,
   newAuthorizeStep,
 } from "../../pipeline/steps/authorize.js";
-import { newGuardReservedLabelsStep } from "../../pipeline/steps/guard-reserved-labels.js";
 import {
-  newAuthorizeVisibilityTransitionStep,
-  newGuardPublicVisibilityStep,
-} from "../../pipeline/steps/visibility-gates.js";
+  loadedTargetAsMethod,
+  newAuthorizeResolvedTargetStep,
+} from "../../pipeline/steps/authorize-resolved-target.js";
+import { versionHistoryTarget } from "../../pipeline/steps/version-history.js";
+import { newGuardReservedLabelsStep } from "../../pipeline/steps/guard-reserved-labels.js";
 import { newBuildUpdateStateStep } from "../../pipeline/steps/build-update-state.js";
 import {
   setAuditFieldsForUpdate,
@@ -90,10 +89,7 @@ import {
   newExtractResourceIdStep,
   newLoadExistingForDeleteStep,
 } from "../../pipeline/steps/delete.js";
-import {
-  findResourceBySlug,
-  requireOrgForReference,
-} from "../../pipeline/steps/helpers.js";
+import { findResourceBySlug } from "../../pipeline/steps/helpers.js";
 import {
   newDeleteSearchIndexStep,
   newIndexSearchStep,
@@ -112,7 +108,16 @@ import {
   TARGET_RESOURCE_KEY,
   newLoadTargetStep,
 } from "../../pipeline/steps/load-target.js";
-import { newNormalizeReferencesStep } from "../../pipeline/steps/references.js";
+import {
+  collectSpecReferences,
+  newGuardReferenceFloorOnEscalationStep,
+  newNormalizeReferencesStep,
+  newValidateReferencesStep,
+} from "../../pipeline/steps/references.js";
+import {
+  collectAgentCallReferences,
+  newValidateAgentCallReferencesStep,
+} from "./agent-call-references.js";
 import {
   newCleanupIamPoliciesStep,
   newCreateAuthorizationTuplesStep,
@@ -150,6 +155,7 @@ import {
   newValidateWorkflowSpecStep,
   truncateHash,
 } from "./steps.js";
+import { newLoadWorkflowByReferenceStep } from "./version-resolution.js";
 import type { WorkflowInstanceCreatorProvider } from "./steps.js";
 
 export interface WorkflowControllerDeps {
@@ -192,7 +198,7 @@ export function registerWorkflowServices(
   });
   router.service(WorkflowQueryController, {
     get: (id, ctx) => get(deps, id, ctx),
-    getByReference: (ref) => getByReference(deps, ref),
+    getByReference: (ref, ctx) => getByReference(deps, ref, ctx),
     listVersions: (input, ctx) => listVersions(deps, input, ctx),
     getVersion: (input, ctx) => getVersion(deps, input, callerIdentityOf(ctx)),
   });
@@ -237,9 +243,10 @@ async function createWorkflow(
     .addStep(newResolveSlugStep())
     .addStep(newCheckDuplicateStep(deps.store))
     .addStep(newBuildNewStateStep())
-    .addStep(newGuardPublicVisibilityStep(deps.authorizer))
     .addStep(newGuardReservedLabelsStep(deps.authorizer))
     .addStep(newNormalizeReferencesStep())
+    .addStep(newValidateReferencesStep(deps.store))
+    .addStep(newValidateAgentCallReferencesStep(deps.store))
     .addStep(newPopulateServerlessValidationStep(deps.logger))
     .addStep(newComputeVersionHashStep(deps.logger))
     .addStep(newPopulateVersionHashStep(true))
@@ -304,6 +311,8 @@ async function update(
     .addStep(newBuildUpdateStateStep())
     .addStep(newGuardReservedLabelsStep(deps.authorizer))
     .addStep(newNormalizeReferencesStep())
+    .addStep(newValidateReferencesStep(deps.store))
+    .addStep(newValidateAgentCallReferencesStep(deps.store))
     .addStep(newPopulateServerlessValidationStepForUpdate(deps.logger))
     .addStep(newComputeVersionHashStep(deps.logger))
     .addStep(newCheckVersionChangedStep(deps.logger))
@@ -410,8 +419,8 @@ async function deleteWorkflow(
 // updateVisibility — update_visibility.go: a targeted metadata update (only
 // metadata.visibility changes; spec/status untouched). The level check runs
 // AFTER load, preserving the cross-edition error precedence: unknown id +
-// bad level = NOT_FOUND on both editions. CW-9's suite block is the wire
-// pin (clientPublicVisibilityWrites, true on local targets).
+// bad level = NOT_FOUND on both editions. The workflow conformance suite's
+// visibility block is the wire pin.
 // ---------------------------------------------------------------------------
 
 const UPDATE_VISIBILITY_WORKFLOW_KEY = "updateVisibilityWorkflow";
@@ -451,10 +460,20 @@ async function updateVisibility(
       newRecordVisibilityBeforeUpdateStep(UPDATE_VISIBILITY_WORKFLOW_KEY),
     )
     .addStep(newValidateVisibilityUpdateStep())
+    // The reference floor's second door: a workflow may not be raised above
+    // the agents its agent_call tasks run.
     .addStep(
-      newAuthorizeVisibilityTransitionStep(
+      newGuardReferenceFloorOnEscalationStep(
+        deps.store,
         UPDATE_VISIBILITY_WORKFLOW_KEY,
-        deps.authorizer,
+        [
+          (row) => collectSpecReferences(WorkflowSchema, row),
+          (row) =>
+            collectAgentCallReferences(
+              (row as Workflow).spec,
+              (row as Workflow).metadata?.org ?? "",
+            ),
+        ],
       ),
     )
     .addStep(newSetWorkflowVisibilityStep())
@@ -831,130 +850,47 @@ async function get(
   return reqCtx.get(TARGET_RESOURCE_KEY) as Workflow;
 }
 
-/** A 64-hex value is an exact content hash; anything else is a tag. */
-const WORKFLOW_HASH_PATTERN = /^[a-f0-9]{64}$/;
-
 /**
- * getByReference — query.go: slug/org resolution plus version resolution.
- * Empty/"latest" → the current head; a version matching the head's hash or
- * tag → the head; otherwise the audit store by hash or tag, with the
- * snapshot's tag overlaid from the audit column (the source of truth) so
- * callers never see a stale embedded tag after a tag move. Like
- * validateSpec, this branching read flow reads more honestly written
- * directly than as a pipeline (Go's own note).
+ * getByReference — the slug/org read plus the version ladder, as a chain:
+ * Authorize (a no-op under the lane's skip annotation) → ValidateProto →
+ * LoadWorkflowByReference (the ladder, version-resolution.ts) →
+ * AuthorizeResolvedTarget, which asks of the loaded head's id exactly what
+ * `get` asks by id, so a slug reveals nothing a member could not read
+ * through the id. The archived snapshot shares the head's id, so the check
+ * on a versioned read is the check on the head.
  */
 async function getByReference(
   deps: WorkflowControllerDeps,
   ref: ApiResourceReference,
+  ctx: HandlerContext,
 ): Promise<Workflow> {
-  if (ref.slug === "") {
-    throw invalidArgumentError("slug is required in reference");
-  }
-
-  // Workflow is org-scoped: its slug is unique only within an org, so an
-  // empty-org reference is under-specified.
-  requireOrgForReference(ApiResourceKind.workflow, ref.org);
-
-  if (
-    ref.kind !== ApiResourceKind.api_resource_kind_unknown &&
-    ref.kind !== ApiResourceKind.workflow
-  ) {
-    // Go renders both sides with .String(): the NAME for defined values and
-    // the bare NUMBER for unknown ones (proto3 open enums preserve them, and
-    // ref.kind carries no defined_only rule) — enumToJson would throw on the
-    // unknown arm (panel finding).
-    const got = ApiResourceKind[ref.kind] ?? String(ref.kind);
-    throw invalidArgumentError(
-      `kind mismatch: expected ${ApiResourceKind[ApiResourceKind.workflow]}, got ${got}`,
-    );
-  }
-
-  let mainWorkflow: Workflow | undefined;
-  try {
-    mainWorkflow = await findResourceBySlug(
-      deps.store,
-      ApiResourceKind.workflow,
-      WorkflowSchema,
-      ref.slug,
-      ref.org,
-    );
-  } catch (error) {
-    // Go wraps the slug scan's store failure (query.go:110) — without this
-    // the raw storage error would cross the wire as Unknown (panel finding).
-    throw internalError(error, "failed to list workflows");
-  }
-  if (mainWorkflow === undefined) {
-    throw notFoundError("workflow", ref.slug);
-  }
-
-  const version = ref.version.trim();
-  if (version === "" || version === "latest") {
-    return mainWorkflow;
-  }
-
-  if (workflowMatchesVersion(mainWorkflow, version)) {
-    return mainWorkflow;
-  }
-
-  const archived = await findAuditWorkflowByVersion(
-    deps.store,
-    mainWorkflow.metadata!.id,
-    version,
+  const reqCtx = new RequestContext(
+    WorkflowQueryController.method.getByReference.input,
+    ref,
+    callerIdentityOf(ctx),
+    kindOf(ctx),
   );
-  if (archived === undefined) {
-    throw notFoundError("workflow version", `${ref.slug}:${version}`);
-  }
-  return archived;
-}
-
-function workflowMatchesVersion(wf: Workflow, version: string): boolean {
-  if (wf.status === undefined) {
-    return false;
-  }
-  if (WORKFLOW_HASH_PATTERN.test(version)) {
-    return wf.status.versionHash === version;
-  }
-  return wf.metadata?.version?.tag === version;
-}
-
-async function findAuditWorkflowByVersion(
-  store: Store,
-  workflowId: string,
-  version: string,
-): Promise<Workflow | undefined> {
-  let rec: AuditRecord;
-  try {
-    rec = WORKFLOW_HASH_PATTERN.test(version)
-      ? await store.getAuditRecordByHash(
-          ApiResourceKind.workflow,
-          workflowId,
-          version,
-        )
-      : await store.getAuditRecordByTag(
-          ApiResourceKind.workflow,
-          workflowId,
-          version,
-        );
-  } catch (error) {
-    if (error instanceof AuditNotFoundError) {
-      return undefined;
-    }
-    throw internalError(error, "failed to query workflow audit by version");
-  }
-
-  let wf: Workflow;
-  try {
-    wf = fromBinary(WorkflowSchema, rec.data);
-  } catch (error) {
-    throw internalError(error, "failed to decode archived workflow version");
-  }
-  // Overlay the authoritative tag (audit column) onto the snapshot's
-  // metadata.version.tag — the snapshot's embedded tag is only correct as
-  // of archival time.
-  wf.metadata ??= create(ApiResourceMetadataSchema);
-  wf.metadata.version ??= create(ApiResourceMetadataVersionSchema);
-  wf.metadata.version.tag = rec.tag;
-  return wf;
+  await newPipeline<typeof WorkflowQueryController.method.getByReference.input>(
+    "workflow-get-by-reference",
+    deps.logger,
+  )
+    .addStep(
+      newAuthorizeStep(
+        WorkflowQueryController.method.getByReference,
+        deps.authorizer,
+      ),
+    )
+    .addStep(newValidateProtoStep())
+    .addStep(newLoadWorkflowByReferenceStep(deps.store))
+    .addStep(
+      newAuthorizeResolvedTargetStep(
+        deps.authorizer,
+        loadedTargetAsMethod(WorkflowQueryController.method.get),
+      ),
+    )
+    .build()
+    .execute(reqCtx);
+  return reqCtx.get(TARGET_RESOURCE_KEY) as Workflow;
 }
 
 // ---------------------------------------------------------------------------
@@ -996,28 +932,23 @@ async function listVersions(
     )
     .addStep(newValidateProtoStep())
     .addStep(newResolveWorkflowBySlugStep(deps.store))
-    .addStep({
-      name: "AuthorizeResolvedWorkflow",
-      async execute(stepCtx): Promise<void> {
-        // The Java WorkflowListVersionsHandler's mid-chain can_view on the
-        // RESOLVED workflow id (20260830.01 ruling Q8 — the DD-007 pattern
-        // "the two traced ListVersions handlers port onto"; the skip
-        // annotation exists because the target resolves from org+slug, not
-        // a request field). Deny copy is the Java handler's byte-pinned
-        // error_msg. The resolve step above already answered NOT_FOUND for
-        // an unknown slug, the load-first order both editions share.
-        await authorizeResolvedResource(
-          deps.authorizer,
-          stepCtx.callerIdentity,
-          {
-            permission: IamPermission.can_view,
-            resourceKind: ApiResourceKind.workflow,
-            resourceId: stepCtx.get(LIST_VERSIONS_WORKFLOW_ID_KEY) as string,
-          },
+    // The Java WorkflowListVersionsHandler's mid-chain can_view on the
+    // RESOLVED workflow id (the skip annotation exists because the target
+    // resolves from org+slug, not a request field); the copy is the Java
+    // handler's byte-pinned error_msg, and the resolve step above already
+    // answered NOT_FOUND for an unknown slug, the load-first order both
+    // editions share.
+    .addStep(
+      newAuthorizeResolvedTargetStep(
+        deps.authorizer,
+        versionHistoryTarget(
+          ApiResourceKind.workflow,
           "unauthorized to view workflow version history",
-        );
-      },
-    })
+          LIST_VERSIONS_WORKFLOW_ID_KEY,
+        ),
+        "AuthorizeResolvedWorkflow",
+      ),
+    )
     .addStep(newLoadAndMapWorkflowVersionsStep(deps.store))
     .build()
     .execute(reqCtx);

package/src/domain/workflow/registry/data/task-kind-registry.json

@@ -1525,7 +1525,7 @@
                   "type": "string"
                 },
                 "org": {
-                  "description": "Organization that owns the referenced resource. When non-empty: must be a valid org slug (lowercase alphanumeric with hyphens, starts with a letter, 1-63 characters). Example: \"stigmer\", \"acme-corp\". When empty: the reference is relative — the server resolves it to the parent resource's organization at write time. All stored and returned references always have org populated (absolute form). Use empty org for same-org references (the common case). Use explicit org for cross-org references (e.g., marketplace resources).",
+                  "description": "Organization that owns the referenced resource. When non-empty: must be a valid org slug (lowercase alphanumeric with hyphens, starts with a letter, 1-63 characters). Example: \"stigmer\", \"acme-corp\". When empty: the reference is relative — the server resolves it to the parent resource's organization at write time. All stored and returned references always have org populated (absolute form). Use empty org for same-org references (the common case). An explicit other org is accepted only when that organization is a platform that shares the resource with yours (visibility_platform).",
                   "maxLength": 63,
                   "pattern": "^$|^[a-z][a-z0-9-]*[a-z0-9]$",
                   "type": "string"

package/src/domain/workflow/validation/task-config-constraints.ts

@@ -105,7 +105,10 @@ function taskConstraintViolations(task: WorkflowTask): string[] {
  * task_config is a Struct again — that is what the walker's recursion is
  * for).
  */
-function configConstraintViolations(task: WorkflowTask, cfg: Message): string[] {
+function configConstraintViolations(
+  task: WorkflowTask,
+  cfg: Message,
+): string[] {
   const schema = taskConfigSchemaFor(task.kind);
   if (schema === undefined) {
     // Unknown kinds were already rejected by validateTaskKinds; an
@@ -129,9 +132,10 @@ function configConstraintViolations(task: WorkflowTask, cfg: Message): string[]
  * The WorkflowTask lists embedded in a control-flow task config, in
  * declaration order — the same recursion set the converter walks
  * (convertForTask/convertForkTask/convertTryTask) and the cloud Java
- * TaskConfigStrictParser mirrors.
+ * TaskConfigStrictParser mirrors. Exported for the write-time reference
+ * collector (../agent-call-references.ts), which walks the same tree.
  */
-function nestedTasks(cfg: Message): WorkflowTask[] {
+export function nestedTasks(cfg: Message): WorkflowTask[] {
   switch (cfg.$typeName) {
     case ForTaskConfigSchema.typeName:
       return (cfg as ForTaskConfig).do;

package/src/domain/workflow/version-resolution.ts

@@ -0,0 +1,166 @@
+/**
+ * Workflow version resolution — the getByReference ladder as a pipeline
+ * step, so the lane can carry the resolved-target authorization the
+ * position-1 annotation cannot express (the target is a slug, not a field).
+ *
+ * The ladder is the Go query.go read, moved here from the direct handler
+ * without a behaviour change: slug required; org required (a workflow's slug
+ * is unique only within an org); kind mismatch refused with Go's rendering
+ * (the NAME for defined values, the bare NUMBER for unknown ones, because
+ * ref.kind carries no defined_only rule and enumToJson would throw on the
+ * unknown arm); the slug scan's store failure wrapped so a raw storage error
+ * never crosses the wire as Unknown; empty or "latest" is the current head;
+ * a version matching the head's hash or tag is the head; otherwise the
+ * audit store by hash or tag, with the snapshot's tag overlaid from the
+ * audit column (the source of truth) so callers never see a stale embedded
+ * tag after a tag move. The resolved row lands under TARGET_RESOURCE_KEY,
+ * the loader contract every getByReference chain shares.
+ *
+ * Deliberately NOT the shared ladder in pipeline/steps/version-history.ts:
+ * that one decodes through the typed audit reads and carries no tag
+ * overlay, so folding the two would change what one of them returns for a
+ * moved tag. Consolidating them is a separate change with its own proof.
+ *
+ * Proven by __tests__/workflow.test.ts's getByReference block and the
+ * conformance suite's workflow reference arms.
+ */
+import { create, fromBinary } from "@bufbuild/protobuf";
+
+import { WorkflowSchema } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/api_pb";
+import type { Workflow } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/api_pb";
+import {
+  ApiResourceMetadataSchema,
+  ApiResourceMetadataVersionSchema,
+} from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import {
+  internalError,
+  invalidArgumentError,
+  notFoundError,
+} from "../../pipeline/errors.js";
+import type { PipelineStep } from "../../pipeline/pipeline.js";
+import type { RequestContext } from "../../pipeline/request-context.js";
+import type { GetByReferenceDesc } from "../../pipeline/steps/authorize-resolved-target.js";
+import {
+  findResourceBySlug,
+  requireOrgForReference,
+} from "../../pipeline/steps/helpers.js";
+import { TARGET_RESOURCE_KEY } from "../../pipeline/steps/load-target.js";
+import { AuditNotFoundError } from "../../store/interface.js";
+import type { AuditRecord, Store } from "../../store/interface.js";
+
+/** A 64-hex value is an exact content hash; anything else is a tag. */
+const WORKFLOW_HASH_PATTERN = /^[a-f0-9]{64}$/;
+
+export function newLoadWorkflowByReferenceStep(
+  store: Store,
+): PipelineStep<GetByReferenceDesc> {
+  return {
+    name: "LoadWorkflowByReference",
+    async execute(ctx: RequestContext<GetByReferenceDesc>): Promise<void> {
+      const ref = ctx.input;
+      if (ref.slug === "") {
+        throw invalidArgumentError("slug is required in reference");
+      }
+
+      requireOrgForReference(ApiResourceKind.workflow, ref.org);
+
+      if (
+        ref.kind !== ApiResourceKind.api_resource_kind_unknown &&
+        ref.kind !== ApiResourceKind.workflow
+      ) {
+        const got = ApiResourceKind[ref.kind] ?? String(ref.kind);
+        throw invalidArgumentError(
+          `kind mismatch: expected ${ApiResourceKind[ApiResourceKind.workflow]}, got ${got}`,
+        );
+      }
+
+      let mainWorkflow: Workflow | undefined;
+      try {
+        mainWorkflow = await findResourceBySlug(
+          store,
+          ApiResourceKind.workflow,
+          WorkflowSchema,
+          ref.slug,
+          ref.org,
+        );
+      } catch (error) {
+        throw internalError(error, "failed to list workflows");
+      }
+      if (mainWorkflow === undefined) {
+        throw notFoundError("workflow", ref.slug);
+      }
+
+      const version = ref.version.trim();
+      if (
+        version === "" ||
+        version === "latest" ||
+        workflowMatchesVersion(mainWorkflow, version)
+      ) {
+        ctx.set(TARGET_RESOURCE_KEY, mainWorkflow);
+        return;
+      }
+
+      const archived = await findAuditWorkflowByVersion(
+        store,
+        mainWorkflow.metadata!.id,
+        version,
+      );
+      if (archived === undefined) {
+        throw notFoundError("workflow version", `${ref.slug}:${version}`);
+      }
+      ctx.set(TARGET_RESOURCE_KEY, archived);
+    },
+  };
+}
+
+function workflowMatchesVersion(wf: Workflow, version: string): boolean {
+  if (wf.status === undefined) {
+    return false;
+  }
+  if (WORKFLOW_HASH_PATTERN.test(version)) {
+    return wf.status.versionHash === version;
+  }
+  return wf.metadata?.version?.tag === version;
+}
+
+async function findAuditWorkflowByVersion(
+  store: Store,
+  workflowId: string,
+  version: string,
+): Promise<Workflow | undefined> {
+  let rec: AuditRecord;
+  try {
+    rec = WORKFLOW_HASH_PATTERN.test(version)
+      ? await store.getAuditRecordByHash(
+          ApiResourceKind.workflow,
+          workflowId,
+          version,
+        )
+      : await store.getAuditRecordByTag(
+          ApiResourceKind.workflow,
+          workflowId,
+          version,
+        );
+  } catch (error) {
+    if (error instanceof AuditNotFoundError) {
+      return undefined;
+    }
+    throw internalError(error, "failed to query workflow audit by version");
+  }
+
+  let wf: Workflow;
+  try {
+    wf = fromBinary(WorkflowSchema, rec.data);
+  } catch (error) {
+    throw internalError(error, "failed to decode archived workflow version");
+  }
+  // Overlay the authoritative tag (audit column) onto the snapshot's
+  // metadata.version.tag — the snapshot's embedded tag is only correct as
+  // of archival time.
+  wf.metadata ??= create(ApiResourceMetadataSchema);
+  wf.metadata.version ??= create(ApiResourceMetadataVersionSchema);
+  wf.metadata.version.tag = rec.tag;
+  return wf;
+}

package/src/domain/workflowexecution/controller.ts

@@ -72,7 +72,10 @@ import {
   TARGET_RESOURCE_KEY,
   newLoadTargetStep,
 } from "../../pipeline/steps/load-target.js";
-import { newNormalizeReferencesStep } from "../../pipeline/steps/references.js";
+import {
+  newNormalizeReferencesStep,
+  newValidateReferencesStep,
+} from "../../pipeline/steps/references.js";
 import {
   newCleanupIamPoliciesStep,
   newCreateAuthorizationTuplesStep,
@@ -299,7 +302,8 @@ async function createExecution(
     .addStep(newCheckDuplicateStep(deps.store))
     .addStep(newBuildNewStateStep())
     .addStep(newGuardReservedLabelsStep(deps.authorizer))
-    .addStep(newNormalizeReferencesStep());
+    .addStep(newNormalizeReferencesStep())
+    .addStep(newValidateReferencesStep(deps.store));
   // The ratified sandbox-acquisition gate slot (blueprint 03 §3a; C4):
   // the Java-verified capacity-gate position — after Authorize and every
   // resolution step (the default instance, like Java's, side-effects
@@ -389,6 +393,7 @@ async function update(
     .addStep(newBuildUpdateStateStep())
     .addStep(newGuardReservedLabelsStep(deps.authorizer))
     .addStep(newNormalizeReferencesStep())
+    .addStep(newValidateReferencesStep(deps.store))
     .addStep(newPersistStep(deps.store))
     .addStep(
       newIndexSearchStep(

package/src/domain/workflowinstance/__tests__/create-authorization.test.ts

@@ -0,0 +1,109 @@
+/**
+ * Pins the create lane's authorization question (steps.ts,
+ * resolveWorkflowInstanceCreateTargets): a personal instance asks
+ * can_execute on the parent workflow with the Java handler's copy; a
+ * default instance the server composed in-process for the parent's
+ * organization asks nothing; the same label from the wire or for another
+ * organization takes the bar; a missing parent throws.
+ */
+import { describe, expect, it } from "vitest";
+import { create } from "@bufbuild/protobuf";
+
+import { WorkflowSchema } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/api_pb";
+import { WorkflowInstanceSchema } from "@stigmer/protos/ai/stigmer/agentic/workflowinstance/v1/api_pb";
+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 { CallerIdentity } from "../../../extensions/identity.js";
+import {
+  DEFAULT_INSTANCE_LABEL,
+  RESERVED_LABEL_TRUE,
+} from "../../../pipeline/apiresource-labels.js";
+import { testCallerIdentity } from "../../../pipeline/__tests__/support.js";
+import { RequestContext } from "../../../pipeline/request-context.js";
+import {
+  PARENT_WORKFLOW_KEY,
+  WORKFLOW_INSTANCE_PARENT_DENIED_MESSAGE,
+  resolveWorkflowInstanceCreateTargets,
+} from "../steps.js";
+
+const parent = create(WorkflowSchema, {
+  metadata: { id: "wf_01parent", name: "nightly", org: "acme" },
+});
+
+function ctxFor(
+  org: string,
+  caller: CallerIdentity,
+  labels: Record<string, string> = {},
+  stashParent = true,
+) {
+  const ctx = new RequestContext(
+    WorkflowInstanceSchema,
+    create(WorkflowInstanceSchema, {
+      metadata: { name: "mine", org, labels },
+      spec: { workflowId: parent.metadata!.id },
+    }),
+    caller,
+    ApiResourceKind.workflow_instance,
+  );
+  if (stashParent) {
+    ctx.set(PARENT_WORKFLOW_KEY, parent);
+  }
+  return ctx;
+}
+
+const DEFAULT_LABELS = { [DEFAULT_INSTANCE_LABEL]: RESERVED_LABEL_TRUE };
+
+describe("resolveWorkflowInstanceCreateTargets", () => {
+  it("a personal instance asks can_execute on the parent workflow", () => {
+    expect(
+      resolveWorkflowInstanceCreateTargets(
+        ctxFor("acme", testCallerIdentity()),
+      ),
+    ).toEqual([
+      {
+        permission: IamPermission.can_execute,
+        resourceKind: ApiResourceKind.workflow,
+        resourceId: "wf_01parent",
+        deniedMessage: WORKFLOW_INSTANCE_PARENT_DENIED_MESSAGE,
+      },
+    ]);
+  });
+
+  it("a default instance the server composed in-process for the parent's organization asks nothing", () => {
+    expect(
+      resolveWorkflowInstanceCreateTargets(
+        ctxFor(
+          "acme",
+          testCallerIdentity({ callerClass: "user", origin: "in-process" }),
+          DEFAULT_LABELS,
+        ),
+      ),
+    ).toEqual([]);
+  });
+
+  it("the label from the wire, or for another organization, takes the bar", () => {
+    expect(
+      resolveWorkflowInstanceCreateTargets(
+        ctxFor("acme", testCallerIdentity(), DEFAULT_LABELS),
+      ),
+    ).toHaveLength(1);
+    expect(
+      resolveWorkflowInstanceCreateTargets(
+        ctxFor(
+          "other-org",
+          testCallerIdentity({ callerClass: "user", origin: "in-process" }),
+          DEFAULT_LABELS,
+        ),
+      ),
+    ).toHaveLength(1);
+  });
+
+  it("a missing parent is a broken chain invariant and throws", () => {
+    expect(() =>
+      resolveWorkflowInstanceCreateTargets(
+        ctxFor("acme", testCallerIdentity(), {}, false),
+      ),
+    ).toThrow("parent workflow not found in context");
+  });
+});