@stigmer/server 3.22.1-dev.20260922095755 → 3.22.1

package/src/domain/workflow/controller.ts

@@ -78,6 +78,10 @@ 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,
@@ -108,16 +112,7 @@ import {
   TARGET_RESOURCE_KEY,
   newLoadTargetStep,
 } from "../../pipeline/steps/load-target.js";
-import {
-  collectSpecReferences,
-  newGuardReferenceFloorOnEscalationStep,
-  newNormalizeReferencesStep,
-  newValidateReferencesStep,
-} from "../../pipeline/steps/references.js";
-import {
-  collectAgentCallReferences,
-  newValidateAgentCallReferencesStep,
-} from "./agent-call-references.js";
+import { newNormalizeReferencesStep } from "../../pipeline/steps/references.js";
 import {
   newCleanupIamPoliciesStep,
   newCreateAuthorizationTuplesStep,
@@ -243,10 +238,9 @@ 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))
@@ -311,8 +305,6 @@ 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))
@@ -419,8 +411,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. The workflow conformance suite's
-// visibility block is the wire pin.
+// bad level = NOT_FOUND on both editions. CW-9's suite block is the wire
+// pin (clientPublicVisibilityWrites, true on local targets).
 // ---------------------------------------------------------------------------
 
 const UPDATE_VISIBILITY_WORKFLOW_KEY = "updateVisibilityWorkflow";
@@ -460,20 +452,10 @@ 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(
-      newGuardReferenceFloorOnEscalationStep(
-        deps.store,
+      newAuthorizeVisibilityTransitionStep(
         UPDATE_VISIBILITY_WORKFLOW_KEY,
-        [
-          (row) => collectSpecReferences(WorkflowSchema, row),
-          (row) =>
-            collectAgentCallReferences(
-              (row as Workflow).spec,
-              (row as Workflow).metadata?.org ?? "",
-            ),
-        ],
+        deps.authorizer,
       ),
     )
     .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). An explicit other org is accepted only when that organization is a platform that shares the resource with yours (visibility_platform).",
+                  "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).",
                   "maxLength": 63,
                   "pattern": "^$|^[a-z][a-z0-9-]*[a-z0-9]$",
                   "type": "string"

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

@@ -105,10 +105,7 @@ 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
@@ -132,10 +129,9 @@ function configConstraintViolations(
  * 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. Exported for the write-time reference
- * collector (../agent-call-references.ts), which walks the same tree.
+ * TaskConfigStrictParser mirrors.
  */
-export function nestedTasks(cfg: Message): WorkflowTask[] {
+function nestedTasks(cfg: Message): WorkflowTask[] {
   switch (cfg.$typeName) {
     case ForTaskConfigSchema.typeName:
       return (cfg as ForTaskConfig).do;

package/src/domain/workflowexecution/controller.ts

@@ -72,10 +72,7 @@ import {
   TARGET_RESOURCE_KEY,
   newLoadTargetStep,
 } from "../../pipeline/steps/load-target.js";
-import {
-  newNormalizeReferencesStep,
-  newValidateReferencesStep,
-} from "../../pipeline/steps/references.js";
+import { newNormalizeReferencesStep } from "../../pipeline/steps/references.js";
 import {
   newCleanupIamPoliciesStep,
   newCreateAuthorizationTuplesStep,
@@ -302,8 +299,7 @@ async function createExecution(
     .addStep(newCheckDuplicateStep(deps.store))
     .addStep(newBuildNewStateStep())
     .addStep(newGuardReservedLabelsStep(deps.authorizer))
-    .addStep(newNormalizeReferencesStep())
-    .addStep(newValidateReferencesStep(deps.store));
+    .addStep(newNormalizeReferencesStep());
   // 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
@@ -393,7 +389,6 @@ 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/controller.ts

@@ -58,6 +58,10 @@ import {
   newAuthorizeResolvedTargetStep,
 } from "../../pipeline/steps/authorize-resolved-target.js";
 import { newGuardReservedLabelsStep } from "../../pipeline/steps/guard-reserved-labels.js";
+import {
+  newAuthorizeVisibilityTransitionStep,
+  newGuardPublicVisibilityStep,
+} from "../../pipeline/steps/visibility-gates.js";
 import {
   newBuildNewStateStep,
   setAuditFieldsForUpdate,
@@ -87,10 +91,7 @@ import {
   TARGET_RESOURCE_KEY,
   newLoadTargetStep,
 } from "../../pipeline/steps/load-target.js";
-import {
-  newNormalizeReferencesStep,
-  newValidateReferencesStep,
-} from "../../pipeline/steps/references.js";
+import { newNormalizeReferencesStep } from "../../pipeline/steps/references.js";
 import {
   newCleanupIamPoliciesStep,
   newCreateAuthorizationTuplesStep,
@@ -197,9 +198,9 @@ async function createInstance(
     .addStep(newValidateSameOrgBusinessRuleStep(deps.logger))
     .addStep(newCheckDuplicateStep(deps.store))
     .addStep(newBuildNewStateStep())
+    .addStep(newGuardPublicVisibilityStep(deps.authorizer))
     .addStep(newGuardReservedLabelsStep(deps.authorizer))
     .addStep(newNormalizeReferencesStep())
-    .addStep(newValidateReferencesStep(deps.store))
     .addStep(newPersistStep(deps.store))
     .addStep(
       newCreateAuthorizationTuplesStep(
@@ -248,7 +249,6 @@ async function update(
     .addStep(newBuildUpdateStateStep())
     .addStep(newGuardReservedLabelsStep(deps.authorizer))
     .addStep(newNormalizeReferencesStep())
-    .addStep(newValidateReferencesStep(deps.store))
     .addStep(newPersistStep(deps.store))
     .addStep(
       newIndexSearchStep(
@@ -407,6 +407,12 @@ async function updateVisibility(
       ),
     )
     .addStep(newValidateVisibilityUpdateStep())
+    .addStep(
+      newAuthorizeVisibilityTransitionStep(
+        UPDATE_VISIBILITY_INSTANCE_KEY,
+        deps.authorizer,
+      ),
+    )
     .addStep(newSetInstanceVisibilityStep())
     .addStep(
       newPersistInstanceStep(

package/src/extensions/__tests__/built-in-authorization-composed.test.ts

@@ -16,9 +16,8 @@
  *     outsider on an EXISTING resource hears PERMISSION_DENIED, the
  *     cloud's answer; `findMyOrganizations` lists what a person may view
  *     and `find` refuses enumeration; `checkMyPermission` tells the truth;
- *     the retired public level is refused for the founder too, as an
- *     invalid level and not a permission question; an unprovisioned
- *     subject writes nothing until provisioned. The LIST lanes are a member's
+ *     nobody sets public visibility; an unprovisioned subject
+ *     writes nothing until provisioned. The LIST lanes are a member's
  *     lists: an outsider lists nothing of an organization they hold no
  *     row in; environments and API keys are their owner's even to the
  *     organization's owner; the library (a search) omits a private agent
@@ -27,9 +26,8 @@
  *     provisioned.
  *   - trusted-local: the permissive default stays (one caller,
  *     nothing to separate; the laptop's rows are stamped `"system"`):
- *     tokenless reads and organization enumeration keep working, and
- *     the retired public level is refused here exactly as it is under
- *     every other posture (the level is gone, not gated).
+ *     tokenless reads, public visibility and organization enumeration all
+ *     keep working.
  *   - a unit's own Authorizer: nothing built in is installed; the unit's
  *     answer stands even against the founder.
  *
@@ -82,6 +80,7 @@ import { loadConfig } from "../../boot/config.js";
 import { composeServer } from "../../boot/compose.js";
 import type { ComposedServer } from "../../boot/compose.js";
 import { metadataOf } from "../../pipeline/steps/shapes.js";
+import { PUBLIC_VISIBILITY_DENY_MESSAGE } from "../../pipeline/steps/visibility-gates.js";
 import type { Store } from "../../store/interface.js";
 import type { Authorizer } from "../authorizer.js";
 import type { ListReadScope } from "../list-read-scope.js";
@@ -133,15 +132,6 @@ function organizationInput(slug: string) {
   };
 }
 
-/**
- * The one sentence for a level a kind does not support, as the agent chain
- * answers it (pipeline/steps/validate-visibility.ts builds it from the
- * kind's config); pinned as bytes because clients render it.
- */
-const PUBLIC_LEVEL_REFUSED_FOR_AGENT =
-  "agent resources cannot be set to visibility_public. " +
-  "Supported visibility levels: visibility_private, visibility_org, visibility_platform.";
-
 function agentInput(
   name: string,
   visibility: ApiResourceVisibility,
@@ -387,14 +377,14 @@ describe("built-in authorizer (composed server, OIDC with no unit Authorizer: th
     );
   });
 
-  it("the retired public level is refused for the founder as an invalid level, before any permission question", async () => {
+  it("nobody sets PUBLIC visibility on an enforcing self-host — the platform gate denies the founder with the policy copy", async () => {
     const failure = await failureOf(
       createClient(AgentCommandController, asFounder()).create(
         agentInput("Public Agent", ApiResourceVisibility.visibility_public),
       ),
     );
-    expect(failure.code).toBe(Code.InvalidArgument);
-    expect(failure.rawMessage).toBe(PUBLIC_LEVEL_REFUSED_FOR_AGENT);
+    expect(failure.code).toBe(Code.PermissionDenied);
+    expect(failure.rawMessage).toBe(PUBLIC_VISIBILITY_DENY_MESSAGE);
   });
 
   describe("the list lanes (the built-in ListReadScope)", () => {
@@ -605,18 +595,20 @@ describe("built-in authorizer (composed server, trusted-local: the permissive de
     expect(read.metadata?.id).toBe(created.metadata!.id);
   });
 
-  it("the laptop keeps organization enumeration and refuses the retired public level like every posture — the level is gone, not gated", async () => {
+  it("the laptop keeps public visibility and organization enumeration — no directory, no platform gate that bites", async () => {
     const anonymous = transportFor(port);
-    const failure = await failureOf(
-      createClient(AgentCommandController, anonymous).create(
-        agentInput(
-          "Public Laptop Agent",
-          ApiResourceVisibility.visibility_public,
-        ),
+    const publicAgent = await createClient(
+      AgentCommandController,
+      anonymous,
+    ).create(
+      agentInput(
+        "Public Laptop Agent",
+        ApiResourceVisibility.visibility_public,
       ),
     );
-    expect(failure.code).toBe(Code.InvalidArgument);
-    expect(failure.rawMessage).toBe(PUBLIC_LEVEL_REFUSED_FOR_AGENT);
+    expect(publicAgent.metadata?.visibility).toBe(
+      ApiResourceVisibility.visibility_public,
+    );
     const all = await createClient(OrganizationQueryController, anonymous).find(
       { org: ORG },
     );
@@ -625,11 +617,6 @@ describe("built-in authorizer (composed server, trusted-local: the permissive de
 
   it("the laptop's lists are the full scan — no scope composed, the rows stamped `system` included", async () => {
     const anonymous = transportFor(port);
-    // A second agent beside the private one the earlier test created, so
-    // the search below proves a scan and not a single-row coincidence.
-    await createClient(AgentCommandController, anonymous).create(
-      agentInput("Second Laptop Agent", ApiResourceVisibility.visibility_org),
-    );
     const environments = createClient(EnvironmentCommandController, anonymous);
     await environments.create(environmentInput("laptop env one"));
     await environments.create(environmentInput("laptop env two"));

package/src/extensions/__tests__/extension-composition.test.ts

@@ -1074,7 +1074,7 @@ describe("extension composition (C2 tuple lifecycle + organization directory)",
     });
   });
 
-  it("updateVisibility fires the set-diff transition (org→private deletes the org shape)", async () => {
+  it("updateVisibility fires the set-diff transition (org→public keeps the floor)", async () => {
     const command = createClient(AgentCommandController, portTransport);
     const agent = await command.create(
       create(AgentSchema, {
@@ -1091,12 +1091,12 @@ describe("extension composition (C2 tuple lifecycle + organization directory)",
     visibilityEvents.length = 0;
     await command.updateVisibility({
       resourceId: agent.metadata?.id ?? "",
-      visibility: ApiResourceVisibility.visibility_private,
+      visibility: ApiResourceVisibility.visibility_public,
     });
     expect(visibilityEvents).toHaveLength(1);
     const event = visibilityEvents[0]!;
-    expect(event.shapesToCreate).toEqual([]);
-    expect(event.shapesToDelete).toEqual(["org-viewer"]);
+    expect(event.shapesToCreate).toEqual(["public-viewer"]);
+    expect(event.shapesToDelete).toEqual([]);
   });
 
   it("delete fires the cleanup event; a cleanup failure never fails the delete", async () => {

package/src/extensions/__tests__/list-read-scope-composed.test.ts

@@ -10,7 +10,7 @@
  *     narrows, blank spans orgs — lane 6),
  *   - activity.listRecentActivity (enumeration verb, two kinds — lane 22),
  *   - search (enumeration verb feeding the engine allowlist, and the
- *     proof that no request shape bypasses it — lane 21),
+ *     crossOrgPublic bypass where FGA is never consulted — lane 21),
  *   - the OUTAGE arm: a throwing scope answers the sanitized INTERNAL,
  *     never an empty (or full!) list;
  *   - the SERVER'S OWN reads over `inProcessTransport` (stigmer#1207):
@@ -277,23 +277,20 @@ describe("list read scope (composed server, fake scope)", () => {
     ]);
   });
 
-  it("search narrows through the engine allowlist on every request shape — nothing bypasses the scope (lane 21)", async () => {
+  it("search narrows through the engine allowlist; crossOrgPublic bypasses the scope (lane 21)", async () => {
     allowed = new Set(["agt_mine"]);
     const search = createClient(SearchService, transport);
     const scoped = await search.search({ query: "scopedagent" });
     expect(scoped.entries.map((e) => e.id)).toEqual(["agt_mine"]);
 
-    // The org-filtered shape asks the scope too: the one request shape
-    // that once skipped it (the retired public level's cross-organization
-    // discovery) no longer exists on the wire.
+    // The Java bypass: public-widened discovery never consults FGA.
     seenKinds.length = 0;
-    const orgScoped = await search.search({
-      kinds: [ApiResourceKind.agent],
+    await search.search({
       query: "scopedagent",
       org: "acme",
+      crossOrgPublic: true,
     });
-    expect(orgScoped.entries.map((e) => e.id)).toEqual(["agt_mine"]);
-    expect(seenKinds).toEqual([ApiResourceKind.agent]);
+    expect(seenKinds).toEqual([]);
   });
 
   it("a scope outage answers the sanitized INTERNAL — never an unscoped or empty success", async () => {

package/src/extensions/authorization-queries.ts

@@ -32,10 +32,9 @@
  * Semantics the controller and the conformance suite rely on (the Java
  * check-handler posture the cloud's client already implements):
  *
- *   - `check` resolves usersets (a grant to `organization:acme#member`
- *     answers true for a member), so "may I read this" is the model's
- *     answer and not a lookup of who was named.
- *   - the two listings never expand usersets, and `listPrincipalIds`
+ *   - `check` answers a public grant (a wildcard principal resolves), so
+ *     "may I read this public agent" is true for anyone.
+ *   - the two listings never expand wildcards, and `listPrincipalIds`
  *     answers DIRECT principals only — a listing is an inventory of who
  *     was named, never a resolution of who could reach.
  *   - contextual policies are evaluated as if held, and nothing is written.
@@ -75,7 +74,7 @@ export interface AuthorizationQueryEngine {
   ): Promise<boolean>;
   /**
    * The ids of `resourceKind` resources on which `principal` holds
-   * `relation` (ListAuthorizedResourceIdsInput's field order). Usersets
+   * `relation` (ListAuthorizedResourceIdsInput's field order). Wildcards
    * are not expanded.
    */
   listResourceIds(
@@ -87,7 +86,7 @@ export interface AuthorizationQueryEngine {
   /**
    * The ids of `principalKind` principals holding `relation` on `resource`
    * (ListAuthorizedPrincipalIdsInput's field order). Direct principals
-   * only; usersets are not expanded.
+   * only; wildcards are not expanded.
    */
   listPrincipalIds(
     resource: ApiResourceRef,

package/src/extensions/list-read-scope.ts

@@ -8,7 +8,7 @@
  * is yours). On a multi-tenant edition the same scans serve OTHER
  * tenants' rows, so the cloud baseline (the Java list handlers) narrows
  * every one of them to the caller's FGA-authorized id set (ListObjects
- * on can_view), with a second guest
+ * on can_view, public wildcards suppressed), with a second guest
  * cookie-label rule on the session and agent-execution lanes.
  *
  * This port is the ONE seam for that fork (DD-007 addendum 3: every

package/src/extensions/resource-authorization.ts

@@ -65,12 +65,14 @@ import type { CallerIdentity } from "./identity.js";
  * The visibility tuple shapes of the shared FGA model, named
  * edition-neutrally. The driver maps each to its tuple:
  *   - org-viewer:      <kind>:<id>#viewer@organization:<org>#viewer
+ *   - public-viewer:   <kind>:<id>#viewer@identity_account:* (conditional)
  *   - platform-viewer: <kind>:<id>#platform_viewer@identity_provider:<idp>#platform_user
  *     (fans out per IdP the org owns — the driver's lookup, not OSS's)
- * Every shape names a bounded set of readers; the model has no shape that
- * reaches every account.
  */
-export type VisibilityTupleShape = "org-viewer" | "platform-viewer";
+export type VisibilityTupleShape =
+  | "org-viewer"
+  | "public-viewer"
+  | "platform-viewer";
 
 /**
  * One resolved structural link from the created resource to a parent

package/src/index.ts

@@ -185,6 +185,7 @@ export {
   newModel,
 } from "./authorization/model/index.js";
 export type {
+  CheckContext,
   ObjectRef,
   Person,
   Subject,
@@ -308,6 +309,19 @@ export { newAuthorizeStep } from "./pipeline/steps/authorize.js";
 // composition never re-derives the set.
 export { isRunGateCheck } from "./pipeline/steps/authorize-run-target.js";
 export { newValidateProtoStep } from "./pipeline/steps/validation.js";
+// The create-shaping steps, for an envelope kind a composition serves
+// itself (a cloud_only kind has no OSS controller to run them): between
+// ValidateProto and its own domain step the composition runs the SAME
+// ResolveSlug and BuildNewState every OSS create runs, so how a slug is
+// derived from a name, how an id is spelled, how status.audit is stamped
+// for the caller and how visibility defaults live exactly once and move
+// together. The RequestContext must carry the kind (its fourth
+// constructor argument) for BuildNewState to pick the id prefix.
+// CheckDuplicate is deliberately not here: it reads this server's Store,
+// and a composition's own table answers that question in a step of the
+// same name over its own repo.
+export { newBuildNewStateStep } from "./pipeline/steps/defaults.js";
+export { newResolveSlugStep } from "./pipeline/steps/slug.js";
 
 // The driver interfaces and the store-fault classes the ratified mapping
 // keys on (typed not-found → NotFound; anything else rethrows as an

package/src/pipeline/apiresource-meta.ts

@@ -266,18 +266,9 @@ function tierRank(tier: ResourceTier): number {
 }
 
 /**
- * Whether a kind may hold a visibility level — the one predicate behind the
- * ValidateVisibility doors on every create and updateVisibility chain.
- *
- * PRIVATE and UNSPECIFIED are always supported (no visibility grant is
- * written for them); ORG and PLATFORM require the matching supports_* flag
- * on the kind's VisibilityConfig, so kinds with no config are private-only.
- * PUBLIC is refused for every kind: the level is retired (it made a row
- * readable to every account on the server), no config may declare it, and
- * the answer is fixed here rather than read from a flag that no longer
- * exists. Every level is named so a level added to the enum must be taught
- * here before any row can hold it; the closing arm is unreachable by wire
- * input, because both doors validate the field `defined_only` first.
+ * Go SupportsVisibility: PRIVATE and UNSPECIFIED are always supported (no
+ * visibility grant); every other level requires the matching supports_*
+ * flag. Kinds with no VisibilityConfig are private-only.
  */
 export function supportsVisibility(
   kind: ApiResourceKind,
@@ -285,19 +276,14 @@ export function supportsVisibility(
 ): boolean {
   const config = getKindMeta(kind).authorization?.visibility;
   switch (visibility) {
-    case ApiResourceVisibility.api_resource_visibility_unspecified:
-    case ApiResourceVisibility.visibility_private:
-      return true;
+    case ApiResourceVisibility.visibility_public:
+      return config?.supportsPublic === true;
     case ApiResourceVisibility.visibility_org:
       return config?.supportsOrg === true;
     case ApiResourceVisibility.visibility_platform:
       return config?.supportsPlatform === true;
-    case ApiResourceVisibility.visibility_public:
-      return false;
-    default: {
-      const exhaustive: never = visibility;
-      throw new Error(`unknown visibility level: ${String(exhaustive)}`);
-    }
+    default:
+      return true;
   }
 }
 
@@ -312,6 +298,9 @@ export function supportedVisibilityLevels(kind: ApiResourceKind): string {
   if (config?.supportsOrg === true) {
     levels += ", visibility_org";
   }
+  if (config?.supportsPublic === true) {
+    levels += ", visibility_public";
+  }
   if (config?.supportsPlatform === true) {
     levels += ", visibility_platform";
   }

package/src/pipeline/steps/__tests__/authorization-tuples.test.ts

@@ -41,10 +41,15 @@ const caller: CallerIdentity = {
 const V = ApiResourceVisibility;
 
 describe("visibilityShapesFor (the reconciler's level→shape policy)", () => {
-  it("agent (blueprint with org floor): org / platform expansions", () => {
+  it("agent (blueprint with org floor): org / public / platform expansions", () => {
     expect([
       ...visibilityShapesFor(ApiResourceKind.agent, V.visibility_org),
     ]).toEqual(["org-viewer"]);
+    expect(
+      [
+        ...visibilityShapesFor(ApiResourceKind.agent, V.visibility_public),
+      ].sort(),
+    ).toEqual(["org-viewer", "public-viewer"]);
     expect(
       [
         ...visibilityShapesFor(ApiResourceKind.agent, V.visibility_platform),
@@ -55,27 +60,25 @@ describe("visibilityShapesFor (the reconciler's level→shape policy)", () => {
     ]).toEqual([]);
   });
 
-  it("the retired public level expands to nothing for every kind — no wildcard shape exists", () => {
-    for (const kind of [
-      ApiResourceKind.agent,
-      ApiResourceKind.workflow_instance,
-      ApiResourceKind.plugin,
-      ApiResourceKind.session,
-    ]) {
-      expect([...visibilityShapesFor(kind, V.visibility_public)]).toEqual([]);
-    }
+  it("workflow_instance (no org floor): public expands to the wildcard shape alone", () => {
+    expect([
+      ...visibilityShapesFor(
+        ApiResourceKind.workflow_instance,
+        V.visibility_public,
+      ),
+    ]).toEqual(["public-viewer"]);
   });
 
   it("session (no visibility config): every level yields nothing, silently", () => {
     expect([
-      ...visibilityShapesFor(ApiResourceKind.session, V.visibility_org),
+      ...visibilityShapesFor(ApiResourceKind.session, V.visibility_public),
     ]).toEqual([]);
     expect([
-      ...visibilityShapesFor(ApiResourceKind.session, V.visibility_platform),
+      ...visibilityShapesFor(ApiResourceKind.session, V.visibility_org),
     ]).toEqual([]);
   });
 
-  it("agent_instance supports org but never platform (tenant isolation)", () => {
+  it("agent_instance supports org+public but never platform (tenant isolation)", () => {
     expect([
       ...visibilityShapesFor(
         ApiResourceKind.agent_instance,
@@ -98,15 +101,15 @@ describe("diffVisibilityShapes (the reconciler's transition matrix, re-pinned)",
     expect(diff.shapesToDelete).toEqual([]);
   });
 
-  it("unspecified→platform creates the platform shape + the org floor", () => {
+  it("unspecified→public creates public + the org floor", () => {
     const diff = diffVisibilityShapes(
       agent,
       V.api_resource_visibility_unspecified,
-      V.visibility_platform,
+      V.visibility_public,
     );
     expect([...diff.shapesToCreate].sort()).toEqual([
       "org-viewer",
-      "platform-viewer",
+      "public-viewer",
     ]);
     expect(diff.shapesToDelete).toEqual([]);
   });
@@ -121,13 +124,23 @@ describe("diffVisibilityShapes (the reconciler's transition matrix, re-pinned)",
     expect(diff.shapesToDelete).toEqual(["org-viewer"]);
   });
 
-  it("platform→org deletes ONLY the platform shape — the shared org floor stays untouched", () => {
+  it("public→org deletes ONLY the wildcard — the shared org shape stays untouched", () => {
     const diff = diffVisibilityShapes(
       agent,
-      V.visibility_platform,
+      V.visibility_public,
       V.visibility_org,
     );
     expect(diff.shapesToCreate).toEqual([]);
+    expect(diff.shapesToDelete).toEqual(["public-viewer"]);
+  });
+
+  it("platform→public swaps the family shape and never touches the org floor", () => {
+    const diff = diffVisibilityShapes(
+      agent,
+      V.visibility_platform,
+      V.visibility_public,
+    );
+    expect(diff.shapesToCreate).toEqual(["public-viewer"]);
     expect(diff.shapesToDelete).toEqual(["platform-viewer"]);
   });