@stigmer/server 3.22.1 → 3.23.1-dev.20260923075205

package/src/domain/skill/transfer/staging.ts

@@ -0,0 +1,191 @@
+/**
+ * Archive staging — how an artifact above the gRPC message cap travels,
+ * on every blob driver, through one code path (#675, stigmer#1219).
+ *
+ * The domain owns the two identities and the mapping between them: the
+ * wire reference a client is handed (`sau_<hex>`, the capability the
+ * push presents) and the staging key the bytes land under in the blob
+ * store (`skills/staging/<hex>.zip`, the surface a sweep targets). A
+ * driver is asked only to sign or stage a PUT for a key it is given, to
+ * read the key back, and to delete it — so the local driver rides the
+ * transfer lane's slot registry and a bucket driver signs a PUT straight
+ * to the bucket, and nothing above this module can tell which.
+ *
+ * Consume reads then deletes: the delete is what keeps a reference
+ * single-use on a bucket, whose signed URL is otherwise repeatable within
+ * its TTL. The delete is best effort and loud — the bytes are already in
+ * hand, a replay of the same reference is a content-addressed no-op, and
+ * the bucket lifecycle rule on the staging prefix sweeps what the delete
+ * missed. On the local driver the same delete retires the staged file the
+ * slot registry would otherwise sweep at expiry.
+ *
+ * A reference the driver cannot read — malformed, never uploaded,
+ * expired, already consumed — is one condition on every driver
+ * ("unknown or expired"): a bucket cannot distinguish them, so neither
+ * does the wire.
+ *
+ * Proven by __tests__/staging.test.ts over a fake driver and over the
+ * real local driver with its slot registry; the conformance suite's
+ * transfer-lane block pins the wire behaviour on both editions.
+ */
+import { randomBytes } from "node:crypto";
+
+import type { ArtifactStorage } from "../../../artifactstorage/artifact-storage.js";
+import { ArtifactStorageNotFoundError } from "../../../artifactstorage/artifact-storage.js";
+import type { Logger } from "../../../boot/logger.js";
+import {
+  DEFAULT_SLOT_TTL_MS,
+  DOWNLOAD_URL_TTL_MS,
+  MAX_ZIP_SIZE,
+  REF_BYTE_LEN,
+  REF_PREFIX,
+  STAGING_KEY_PREFIX,
+} from "../constants.js";
+import { SlotUnknownError } from "./slots.js";
+
+/** The hex the reference and the staging key share; 128 bits, lowercase. */
+const HEX = new RegExp(`^[0-9a-f]{${REF_BYTE_LEN * 2}}$`);
+const STAGED_ARCHIVE_SUFFIX = ".zip";
+
+/** The shared hex of a well-formed reference or key, else undefined. */
+function hexBetween(
+  value: string,
+  prefix: string,
+  suffix: string,
+): string | undefined {
+  if (!value.startsWith(prefix) || !value.endsWith(suffix)) {
+    return undefined;
+  }
+  const hex = value.slice(prefix.length, value.length - suffix.length);
+  return HEX.test(hex) ? hex : undefined;
+}
+
+/** A fresh upload reference: the prefix and 128 random bits, hex. */
+export function newUploadRef(): string {
+  return REF_PREFIX + randomBytes(REF_BYTE_LEN).toString("hex");
+}
+
+/**
+ * The staging key a reference's bytes land under, or undefined when the
+ * reference is not one this server could have minted. Refs arrive from
+ * clients (the push request, the lane's URL path), so the shape is
+ * checked before it becomes a storage key.
+ */
+export function stagingKeyOf(ref: string): string | undefined {
+  const hex = hexBetween(ref, REF_PREFIX, "");
+  return hex === undefined
+    ? undefined
+    : `${STAGING_KEY_PREFIX}${hex}${STAGED_ARCHIVE_SUFFIX}`;
+}
+
+/**
+ * The reference for a staging key this module minted. Keys reach here from
+ * the domain's own mint, never from a client, so a foreign shape is a
+ * programming error and throws.
+ */
+export function uploadRefOf(stagingKey: string): string {
+  const hex = hexBetween(stagingKey, STAGING_KEY_PREFIX, STAGED_ARCHIVE_SUFFIX);
+  if (hex === undefined) {
+    throw new Error(`${stagingKey} is not a staging key this domain minted`);
+  }
+  return REF_PREFIX + hex;
+}
+
+/** What createArtifactUploadUrl hands the client. */
+export interface StagedUpload {
+  /** The single-use reference the push presents. */
+  readonly ref: string;
+  /** Accepts one HTTP PUT of exactly the declared byte count. */
+  readonly url: string;
+  /** How long the reference and the URL stay valid. */
+  readonly ttlMs: number;
+}
+
+/** What getArtifactDownloadUrl hands the client. */
+export interface DownloadCapability {
+  readonly url: string;
+  /** The floor of the URL's validity (DOWNLOAD_URL_TTL_MS). */
+  readonly ttlMs: number;
+}
+
+/** The staging port both archive kinds (skills, plugins) push through. */
+export interface ArchiveStaging {
+  /** Mints a reference and the URL its bytes are PUT to. */
+  mint(declaredSizeBytes: number): Promise<StagedUpload>;
+  /**
+   * Reads the staged bytes for a reference and retires it. Throws
+   * SlotUnknownError when the driver holds nothing under the reference;
+   * any other failure is the driver's and propagates as an infrastructure
+   * fault.
+   */
+  consume(ref: string): Promise<Uint8Array>;
+  /** A time-limited download URL for a stored archive key. */
+  downloadUrl(storageKey: string): Promise<DownloadCapability>;
+}
+
+export function newArchiveStaging(
+  driver: ArtifactStorage,
+  logger: Logger,
+): ArchiveStaging {
+  return {
+    async mint(declaredSizeBytes) {
+      // The controllers refuse over-limit declarations with the limit in
+      // the message before reaching here; this is the module's own
+      // invariant, so no driver is ever asked to stage more than the
+      // archive ceiling.
+      if (declaredSizeBytes <= 0 || declaredSizeBytes > MAX_ZIP_SIZE) {
+        throw new Error(
+          `declared size ${declaredSizeBytes} outside (0, ${MAX_ZIP_SIZE}]`,
+        );
+      }
+      const ref = newUploadRef();
+      const key = stagingKeyOf(ref);
+      if (key === undefined) {
+        throw new Error(`minted reference ${ref} has no staging key`);
+      }
+      const presigned = await driver.presignPut(
+        key,
+        declaredSizeBytes,
+        DEFAULT_SLOT_TTL_MS,
+      );
+      return { ref, url: presigned.url, ttlMs: presigned.ttlMs };
+    },
+
+    async consume(ref) {
+      const key = stagingKeyOf(ref);
+      if (key === undefined) {
+        throw new SlotUnknownError();
+      }
+      let data: Uint8Array;
+      try {
+        // The allocation is bounded by construction: a bucket accepts only
+        // the signed Content-Length, the slot registry only the reserved
+        // size, and both were checked against MAX_ZIP_SIZE at mint.
+        data = await driver.download(key);
+      } catch (error) {
+        if (error instanceof ArtifactStorageNotFoundError) {
+          throw new SlotUnknownError();
+        }
+        throw error;
+      }
+      try {
+        await driver.delete(key);
+      } catch (error) {
+        logger.error("failed to delete consumed staged artifact", {
+          stagingKey: key,
+          error: error instanceof Error ? error.message : String(error),
+        });
+      }
+      return data;
+    },
+
+    async downloadUrl(storageKey) {
+      const url = await driver.getSignedUrl(
+        storageKey,
+        DOWNLOAD_URL_TTL_MS,
+        "",
+      );
+      return { url, ttlMs: DOWNLOAD_URL_TTL_MS };
+    },
+  };
+}

package/src/domain/workflow/__tests__/agent-call-references.test.ts

@@ -0,0 +1,222 @@
+/**
+ * Pins the workflow domain's collector for the reference rule
+ * (../agent-call-references.ts): the strict `slug` / `org/slug` parser and
+ * its refusal copy, the walk over top-level, nested and compensate tasks
+ * in declaration order with the bare form resolved to the workflow's
+ * organization, a config that does not decode skipped rather than
+ * double-reported, and the step over a real store answering the rule's
+ * verdicts — a missing agent with the rule's copy, another organization's
+ * org-visible agent with the one cross-organization sentence, a
+ * platform-visible one admitted.
+ */
+import { create } from "@bufbuild/protobuf";
+import { Code, ConnectError } from "@connectrpc/connect";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import { WorkflowSchema } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/api_pb";
+import { WorkflowTaskKind } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/enum_pb";
+import type { WorkflowSpec } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/spec_pb";
+import { WorkflowSpecSchema } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/spec_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 { RequestContext } from "../../../pipeline/request-context.js";
+import { testCallerIdentity } from "../../../pipeline/__tests__/support.js";
+import {
+  missingReferencesMessage,
+  notAvailableReferenceMessage,
+  referenceTargetKind,
+} from "../../../pipeline/steps/references.js";
+import type { SqliteStore } from "../../../store/sqlite/store.js";
+import { tempStore } from "../../../store/sqlite/__tests__/support.js";
+import {
+  collectAgentCallReferences,
+  malformedAgentReferenceMessage,
+  newValidateAgentCallReferencesStep,
+  parseAgentReference,
+} from "../agent-call-references.js";
+
+const V = ApiResourceVisibility;
+const AGENT = referenceTargetKind(ApiResourceKind.agent)!;
+
+function agentCall(name: string, agent: string) {
+  return {
+    name,
+    kind: WorkflowTaskKind.agent_call,
+    taskConfig: { agent, message: "do the thing" },
+  };
+}
+
+function specOf(tasks: ReadonlyArray<Record<string, unknown>>): WorkflowSpec {
+  return create(WorkflowSpecSchema, { tasks } as never);
+}
+
+describe("parseAgentReference", () => {
+  it("accepts `slug` and `org/slug` and nothing else", () => {
+    expect(parseAgentReference("reviewer")).toEqual({
+      org: "",
+      slug: "reviewer",
+    });
+    expect(parseAgentReference("acme/reviewer")).toEqual({
+      org: "acme",
+      slug: "reviewer",
+    });
+    for (const malformed of ["", "/reviewer", "acme/", "a/b/c", "//"]) {
+      expect(parseAgentReference(malformed), malformed).toBeUndefined();
+    }
+  });
+});
+
+describe("collectAgentCallReferences", () => {
+  it("collects top-level, nested and compensate agent_call tasks in declaration order, the bare form resolved to the workflow's organization", () => {
+    const spec = specOf([
+      agentCall("first", "reviewer"),
+      {
+        name: "loop",
+        kind: WorkflowTaskKind.for_each,
+        taskConfig: {
+          each: "item",
+          in: "${ .items }",
+          // A nested task inside the Struct is JSON: proto field names.
+          do: [
+            {
+              name: "inner",
+              kind: "agent_call",
+              task_config: { agent: "globex/summarizer", message: "sum" },
+            },
+          ],
+        },
+        compensate: [agentCall("undo", "cleaner")],
+      },
+      {
+        name: "pause",
+        kind: WorkflowTaskKind.wait,
+        taskConfig: { duration: {} },
+      },
+    ]);
+    expect(collectAgentCallReferences(spec, "acme")).toEqual([
+      { kind: ApiResourceKind.agent, org: "acme", slug: "reviewer" },
+      { kind: ApiResourceKind.agent, org: "globex", slug: "summarizer" },
+      { kind: ApiResourceKind.agent, org: "acme", slug: "cleaner" },
+    ]);
+  });
+
+  it("refuses a malformed agent string naming the task", () => {
+    const spec = specOf([agentCall("broken", "a/b/c")]);
+    expect(() => collectAgentCallReferences(spec, "acme")).toThrow(
+      malformedAgentReferenceMessage("broken", "a/b/c"),
+    );
+    let error: unknown;
+    try {
+      collectAgentCallReferences(spec, "acme");
+    } catch (e) {
+      error = e;
+    }
+    expect((error as ConnectError).code).toBe(Code.InvalidArgument);
+  });
+
+  it("skips a config that does not decode — the spec validation step has already refused it", () => {
+    const spec = specOf([
+      {
+        name: "odd",
+        kind: WorkflowTaskKind.agent_call,
+        taskConfig: { agent: "reviewer", not_a_field: true },
+      },
+    ]);
+    expect(collectAgentCallReferences(spec, "acme")).toEqual([]);
+    expect(collectAgentCallReferences(undefined, "acme")).toEqual([]);
+  });
+});
+
+describe("ValidateAgentCallReferences over a store", () => {
+  let store: SqliteStore;
+  let cleanup: () => Promise<void>;
+
+  beforeEach(() => {
+    const temp = tempStore();
+    store = temp.store;
+    cleanup = temp.cleanup;
+  });
+
+  afterEach(async () => {
+    await cleanup();
+  });
+
+  async function seedAgent(
+    id: string,
+    org: string,
+    slug: string,
+    visibility: ApiResourceVisibility,
+  ): Promise<void> {
+    await store.saveResource(
+      ApiResourceKind.agent,
+      id,
+      AgentSchema,
+      create(AgentSchema, {
+        apiVersion: "agentic.stigmer.ai/v1",
+        kind: "Agent",
+        metadata: { id, name: slug, slug, org, visibility },
+        spec: { instructions: "a conformant instruction body" },
+      }),
+    );
+  }
+
+  function workflowCalling(...agents: string[]) {
+    return create(WorkflowSchema, {
+      apiVersion: "agentic.stigmer.ai/v1",
+      kind: "Workflow",
+      metadata: { name: "Pipeline", org: "acme", visibility: V.visibility_org },
+      spec: specOf(agents.map((agent, i) => agentCall(`call_${i}`, agent))),
+    });
+  }
+
+  async function run(workflow: ReturnType<typeof workflowCalling>) {
+    const ctx = new RequestContext(
+      WorkflowSchema,
+      workflow,
+      testCallerIdentity(),
+      ApiResourceKind.workflow,
+    );
+    try {
+      await newValidateAgentCallReferencesStep(store).execute(ctx);
+      return undefined;
+    } catch (error) {
+      return error;
+    }
+  }
+
+  it("a missing agent is refused with the rule's copy; an existing one passes", async () => {
+    const error = await run(workflowCalling("reviewer"));
+    expect(error).toBeInstanceOf(ConnectError);
+    expect((error as ConnectError).code).toBe(Code.FailedPrecondition);
+    expect((error as ConnectError).rawMessage).toBe(
+      missingReferencesMessage(AGENT, [{ slug: "reviewer", org: "acme" }]),
+    );
+    await seedAgent("agt_1", "acme", "reviewer", V.visibility_org);
+    expect(await run(workflowCalling("reviewer"))).toBeUndefined();
+  });
+
+  it("another organization's agent is admitted only at platform visibility, with the one sentence otherwise", async () => {
+    await seedAgent("agt_shared", "globex", "shared", V.visibility_platform);
+    await seedAgent("agt_internal", "globex", "internal", V.visibility_org);
+    expect(await run(workflowCalling("globex/shared"))).toBeUndefined();
+    const error = await run(workflowCalling("globex/internal"));
+    expect((error as ConnectError).rawMessage).toBe(
+      notAvailableReferenceMessage(AGENT, {
+        kind: ApiResourceKind.agent,
+        org: "globex",
+        slug: "internal",
+      }),
+    );
+  });
+
+  it("the floor holds for the agent a workflow calls: an org-visible workflow may not call a private agent", async () => {
+    await seedAgent("agt_mine", "acme", "mine", V.visibility_private);
+    const error = await run(workflowCalling("mine"));
+    expect((error as ConnectError).code).toBe(Code.FailedPrecondition);
+    expect((error as ConnectError).rawMessage).toContain(
+      "referenced agent 'acme/mine' is visibility_private while this resource is visibility_org",
+    );
+  });
+});

package/src/domain/workflow/agent-call-references.ts

@@ -0,0 +1,157 @@
+/**
+ * ValidateAgentCallReferences — the second collector for the reference rule
+ * (pipeline/steps/references.ts): a workflow's `agent_call` tasks name their
+ * agent as a STRING, `"slug"` or `"org/slug"`, inside a `google.protobuf.Struct`
+ * config the generic spec walker cannot see, so the rule would never meet
+ * them. This step parses each task's config through the converter's own
+ * strict decoder (`unmarshalTaskConfig`, the one reader of a task config),
+ * walks nested control-flow tasks exactly as the constraint validator does,
+ * turns every `agent` string into a reference with the workflow as parent,
+ * and asks the rule's one function — same clauses, same copy. It lives in
+ * the workflow domain and not inside `InProcessValidator` because the
+ * validator is pure over the spec by design and a rule that reads the
+ * target's row cannot be.
+ *
+ * The parser here is STRICT: exactly `slug` or `org/slug`, both segments
+ * non-empty, anything else refused at write naming the task. Two lenient
+ * readers of the same string exist downstream and disagree with each other
+ * (the runner's `parseAgentReference` in activities/call-agent.ts splits on
+ * the first `/` and drops a third segment; the CLI's `parseReference` in
+ * client-apps/cli/src/resources/reference.ts refuses a leading slash);
+ * refusing every malformed shape here means neither ever meets one. The
+ * three cannot share code — the packages share only the protos — so the
+ * execution conformance suite is where their agreement is proven.
+ *
+ * Runs after NormalizeReferences and ValidateReferences on the workflow
+ * create and update chains, so the org the walk sees is the workflow's own
+ * for a bare slug. Proven by __tests__/agent-call-references.test.ts and
+ * the workflow conformance suite's reference arm.
+ */
+import type { WorkflowSchema } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/api_pb";
+import type { AgentCallTaskConfig } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/tasks/agent_call_pb";
+import type {
+  WorkflowSpec,
+  WorkflowTask,
+} from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/spec_pb";
+import { WorkflowTaskKind } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/enum_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import type { Store } from "../../store/interface.js";
+import { internalError, invalidArgumentError } from "../../pipeline/errors.js";
+import type { PipelineStep } from "../../pipeline/pipeline.js";
+import type { RequestContext } from "../../pipeline/request-context.js";
+import type {
+  ReferenceParent,
+  SpecReference,
+} from "../../pipeline/steps/references.js";
+import { checkReferences } from "../../pipeline/steps/references.js";
+import { metadataOf } from "../../pipeline/steps/shapes.js";
+import { unmarshalTaskConfig } from "./converter/unmarshal.js";
+import { nestedTasks } from "./validation/task-config-constraints.js";
+
+/** The one sentence for an `agent` string that is neither `slug` nor `org/slug`. */
+export function malformedAgentReferenceMessage(
+  taskName: string,
+  agent: string,
+): string {
+  return `task '${taskName}': agent '${agent}' is not a reference; write 'slug' for an agent of this organization or 'org/slug' for another organization's.`;
+}
+
+/**
+ * `slug` or `org/slug` → the reference, with `org` empty for the bare form
+ * (the caller fills the parent's). Returns undefined for any other shape.
+ */
+export function parseAgentReference(
+  agent: string,
+): { readonly org: string; readonly slug: string } | undefined {
+  const parts = agent.split("/");
+  if (parts.length === 1) {
+    return parts[0] === "" ? undefined : { org: "", slug: parts[0]! };
+  }
+  if (parts.length === 2 && parts[0] !== "" && parts[1] !== "") {
+    return { org: parts[0]!, slug: parts[1]! };
+  }
+  return undefined;
+}
+
+/**
+ * Every `agent_call` task's agent as a reference, nested tasks included in
+ * declaration order, the bare form resolved to `parentOrg`. Throws
+ * INVALID_ARGUMENT on the first malformed string. A config that does not
+ * decode is skipped: the spec validation step has already refused the
+ * workflow for it, and this collector never double-reports.
+ */
+export function collectAgentCallReferences(
+  spec: WorkflowSpec | undefined,
+  parentOrg: string,
+): SpecReference[] {
+  const refs: SpecReference[] = [];
+  if (spec === undefined) {
+    return refs;
+  }
+  const visit = (task: WorkflowTask): void => {
+    if (task.taskConfig !== undefined) {
+      let config;
+      try {
+        config = unmarshalTaskConfig(task.kind, task.taskConfig);
+      } catch {
+        config = undefined;
+      }
+      if (config !== undefined) {
+        if (task.kind === WorkflowTaskKind.agent_call) {
+          const agent = (config as AgentCallTaskConfig).agent;
+          const parsed = parseAgentReference(agent);
+          if (parsed === undefined) {
+            throw invalidArgumentError(
+              malformedAgentReferenceMessage(task.name, agent),
+            );
+          }
+          refs.push({
+            kind: ApiResourceKind.agent,
+            org: parsed.org === "" ? parentOrg : parsed.org,
+            slug: parsed.slug,
+          });
+        }
+        for (const nested of nestedTasks(config)) {
+          visit(nested);
+        }
+      }
+    }
+    for (const compensate of task.compensate) {
+      visit(compensate);
+    }
+  };
+  for (const task of spec.tasks) {
+    visit(task);
+  }
+  return refs;
+}
+
+export function newValidateAgentCallReferencesStep(
+  store: Store,
+): PipelineStep<typeof WorkflowSchema> {
+  return {
+    name: "ValidateAgentCallReferences",
+    async execute(ctx: RequestContext<typeof WorkflowSchema>): Promise<void> {
+      const metadata = metadataOf(ctx.newState);
+      if (metadata === undefined) {
+        throw internalError(
+          new Error("resource metadata is nil"),
+          "validate agent_call references",
+        );
+      }
+      const refs = collectAgentCallReferences(ctx.newState.spec, metadata.org);
+      if (refs.length === 0) {
+        return;
+      }
+      const parent: ReferenceParent = {
+        org: metadata.org,
+        visibility: metadata.visibility,
+      };
+      const refusal = await checkReferences(store, parent, refs);
+      if (refusal !== undefined) {
+        throw refusal;
+      }
+    },
+  };
+}

package/src/domain/workflow/controller.ts

@@ -78,10 +78,6 @@ import {
 } 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 {
-  newAuthorizeVisibilityTransitionStep,
-  newGuardPublicVisibilityStep,
-} from "../../pipeline/steps/visibility-gates.js";
 import { newBuildUpdateStateStep } from "../../pipeline/steps/build-update-state.js";
 import {
   setAuditFieldsForUpdate,
@@ -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,
@@ -238,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))
@@ -305,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))
@@ -411,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";
@@ -452,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())

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"