@stigmer/server 3.23.0 → 3.24.0

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

@@ -1362,7 +1362,7 @@
         {
           "name": "agent",
           "displayName": "Agent",
-          "description": "Agent reference in \"org/slug\" or \"slug\" format. - \"slug\" only: uses the workflow's organization - \"org/slug\": explicit organization reference Examples: \"code-reviewer\", \"stigmer/code-reviewer\", \"acme/data-analyst\" Required field.",
+          "description": "Agent to invoke, as \"slug\", \"org/slug\", or a value holding a runtime expression. - \"slug\": an agent of the organization the workflow runs in; checked when the workflow is saved, against the workflow's own organization - \"org/slug\": that organization's agent; checked when the workflow is saved, and another organization's agent must be shared at platform visibility - a value holding \"${ ... }\", \"${.env_vars.KEY}\" or \"${.secrets.KEY}\": resolved to \"slug\" or \"org/slug\" when the task runs, and read as the person who ran the workflow Examples: \"code-reviewer\", \"acme/data-analyst\", \"${.env_vars.TEAM_ORG}/assistant\" Required field.",
           "type": "string",
           "required": true,
           "groupId": "core",
@@ -1470,7 +1470,7 @@
         "additionalProperties": false,
         "properties": {
           "agent": {
-            "description": "Agent reference in \"org/slug\" or \"slug\" format. - \"slug\" only: uses the workflow's organization - \"org/slug\": explicit organization reference Examples: \"code-reviewer\", \"stigmer/code-reviewer\", \"acme/data-analyst\" Required field.",
+            "description": "Agent to invoke, as \"slug\", \"org/slug\", or a value holding a runtime expression. - \"slug\": an agent of the organization the workflow runs in; checked when the workflow is saved, against the workflow's own organization - \"org/slug\": that organization's agent; checked when the workflow is saved, and another organization's agent must be shared at platform visibility - a value holding \"${ ... }\", \"${.env_vars.KEY}\" or \"${.secrets.KEY}\": resolved to \"slug\" or \"org/slug\" when the task runs, and read as the person who ran the workflow Examples: \"code-reviewer\", \"acme/data-analyst\", \"${.env_vars.TEAM_ORG}/assistant\" Required field.",
             "maxLength": 127,
             "minLength": 1,
             "type": "string"
@@ -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/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/controller.ts

@@ -58,10 +58,6 @@ 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,
@@ -91,7 +87,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,
@@ -198,9 +197,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(
@@ -249,6 +248,7 @@ async function update(
     .addStep(newBuildUpdateStateStep())
     .addStep(newGuardReservedLabelsStep(deps.authorizer))
     .addStep(newNormalizeReferencesStep())
+    .addStep(newValidateReferencesStep(deps.store))
     .addStep(newPersistStep(deps.store))
     .addStep(
       newIndexSearchStep(
@@ -407,12 +407,6 @@ 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,8 +16,9 @@
  *     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;
- *     nobody sets public visibility; an unprovisioned subject
- *     writes nothing until provisioned. The LIST lanes are a member's
+ *     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
  *     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
@@ -26,8 +27,9 @@
  *     provisioned.
  *   - trusted-local: the permissive default stays (one caller,
  *     nothing to separate; the laptop's rows are stamped `"system"`):
- *     tokenless reads, public visibility and organization enumeration all
- *     keep working.
+ *     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).
  *   - a unit's own Authorizer: nothing built in is installed; the unit's
  *     answer stands even against the founder.
  *
@@ -80,7 +82,6 @@ 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";
@@ -132,6 +133,15 @@ 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,
@@ -377,14 +387,14 @@ describe("built-in authorizer (composed server, OIDC with no unit Authorizer: th
     );
   });
 
-  it("nobody sets PUBLIC visibility on an enforcing self-host — the platform gate denies the founder with the policy copy", async () => {
+  it("the retired public level is refused for the founder as an invalid level, before any permission question", async () => {
     const failure = await failureOf(
       createClient(AgentCommandController, asFounder()).create(
         agentInput("Public Agent", ApiResourceVisibility.visibility_public),
       ),
     );
-    expect(failure.code).toBe(Code.PermissionDenied);
-    expect(failure.rawMessage).toBe(PUBLIC_VISIBILITY_DENY_MESSAGE);
+    expect(failure.code).toBe(Code.InvalidArgument);
+    expect(failure.rawMessage).toBe(PUBLIC_LEVEL_REFUSED_FOR_AGENT);
   });
 
   describe("the list lanes (the built-in ListReadScope)", () => {
@@ -595,20 +605,18 @@ describe("built-in authorizer (composed server, trusted-local: the permissive de
     expect(read.metadata?.id).toBe(created.metadata!.id);
   });
 
-  it("the laptop keeps public visibility and organization enumeration — no directory, no platform gate that bites", async () => {
+  it("the laptop keeps organization enumeration and refuses the retired public level like every posture — the level is gone, not gated", async () => {
     const anonymous = transportFor(port);
-    const publicAgent = await createClient(
-      AgentCommandController,
-      anonymous,
-    ).create(
-      agentInput(
-        "Public Laptop Agent",
-        ApiResourceVisibility.visibility_public,
+    const failure = await failureOf(
+      createClient(AgentCommandController, anonymous).create(
+        agentInput(
+          "Public Laptop Agent",
+          ApiResourceVisibility.visibility_public,
+        ),
       ),
     );
-    expect(publicAgent.metadata?.visibility).toBe(
-      ApiResourceVisibility.visibility_public,
-    );
+    expect(failure.code).toBe(Code.InvalidArgument);
+    expect(failure.rawMessage).toBe(PUBLIC_LEVEL_REFUSED_FOR_AGENT);
     const all = await createClient(OrganizationQueryController, anonymous).find(
       { org: ORG },
     );
@@ -617,6 +625,11 @@ 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→public keeps the floor)", async () => {
+  it("updateVisibility fires the set-diff transition (org→private deletes the org shape)", 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_public,
+      visibility: ApiResourceVisibility.visibility_private,
     });
     expect(visibilityEvents).toHaveLength(1);
     const event = visibilityEvents[0]!;
-    expect(event.shapesToCreate).toEqual(["public-viewer"]);
-    expect(event.shapesToDelete).toEqual([]);
+    expect(event.shapesToCreate).toEqual([]);
+    expect(event.shapesToDelete).toEqual(["org-viewer"]);
   });
 
   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
- *     crossOrgPublic bypass where FGA is never consulted — lane 21),
+ *     proof that no request shape bypasses it — 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,20 +277,23 @@ describe("list read scope (composed server, fake scope)", () => {
     ]);
   });
 
-  it("search narrows through the engine allowlist; crossOrgPublic bypasses the scope (lane 21)", async () => {
+  it("search narrows through the engine allowlist on every request shape — nothing 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 Java bypass: public-widened discovery never consults FGA.
+    // 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.
     seenKinds.length = 0;
-    await search.search({
+    const orgScoped = await search.search({
+      kinds: [ApiResourceKind.agent],
       query: "scopedagent",
       org: "acme",
-      crossOrgPublic: true,
     });
-    expect(seenKinds).toEqual([]);
+    expect(orgScoped.entries.map((e) => e.id)).toEqual(["agt_mine"]);
+    expect(seenKinds).toEqual([ApiResourceKind.agent]);
   });
 
   it("a scope outage answers the sanitized INTERNAL — never an unscoped or empty success", async () => {

package/src/extensions/authorization-queries.ts

@@ -32,9 +32,10 @@
  * Semantics the controller and the conformance suite rely on (the Java
  * check-handler posture the cloud's client already implements):
  *
- *   - `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`
+ *   - `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`
  *     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.
@@ -74,7 +75,7 @@ export interface AuthorizationQueryEngine {
   ): Promise<boolean>;
   /**
    * The ids of `resourceKind` resources on which `principal` holds
-   * `relation` (ListAuthorizedResourceIdsInput's field order). Wildcards
+   * `relation` (ListAuthorizedResourceIdsInput's field order). Usersets
    * are not expanded.
    */
   listResourceIds(
@@ -86,7 +87,7 @@ export interface AuthorizationQueryEngine {
   /**
    * The ids of `principalKind` principals holding `relation` on `resource`
    * (ListAuthorizedPrincipalIdsInput's field order). Direct principals
-   * only; wildcards are not expanded.
+   * only; usersets 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, public wildcards suppressed), with a second guest
+ * on can_view), 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,14 +65,12 @@ 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"
-  | "public-viewer"
-  | "platform-viewer";
+export type VisibilityTupleShape = "org-viewer" | "platform-viewer";
 
 /**
  * One resolved structural link from the created resource to a parent

package/src/index.ts

@@ -185,7 +185,6 @@ export {
   newModel,
 } from "./authorization/model/index.js";
 export type {
-  CheckContext,
   ObjectRef,
   Person,
   Subject,

package/src/pipeline/__tests__/supports-visibility.test.ts

@@ -0,0 +1,112 @@
+/**
+ * Pins `supportsVisibility` and `supportedVisibilityLevels`
+ * (pipeline/apiresource-meta.ts), the one predicate behind the
+ * ValidateVisibility doors on every create and updateVisibility chain.
+ *
+ * The retired public level is the reason this file exists: no kind config
+ * declares it any more, so the predicate cannot read a flag for it and must
+ * answer from its own text. The first test walks EVERY kind that has
+ * `kind_meta` and asserts the level is refused; the door is one function,
+ * and this is the pin that it holds for kinds nobody thought to try. The
+ * rest of the file pins the levels that remain against the proto's
+ * declarations for the kinds whose configs differ (a blueprint, an
+ * instance, an org-only kind, a kind with no config), and the copy fragment
+ * both editions build the INVALID_ARGUMENT sentence from.
+ */
+import { describe, expect, it } from "vitest";
+
+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 {
+  getKindMeta,
+  supportedVisibilityLevels,
+  supportsVisibility,
+} from "../apiresource-meta.js";
+
+const V = ApiResourceVisibility;
+
+/** Every enum member that carries kind_meta (the unknown kind does not). */
+const KINDS_WITH_META: ApiResourceKind[] = Object.values(ApiResourceKind)
+  .filter((value): value is ApiResourceKind => typeof value === "number")
+  .filter((kind) => {
+    try {
+      getKindMeta(kind);
+      return true;
+    } catch {
+      return false;
+    }
+  });
+
+describe("supportsVisibility", () => {
+  it("refuses the retired public level for every kind", () => {
+    expect(KINDS_WITH_META.length).toBeGreaterThan(20);
+    for (const kind of KINDS_WITH_META) {
+      expect(supportsVisibility(kind, V.visibility_public)).toBe(false);
+    }
+  });
+
+  it("private and unspecified are supported by every kind", () => {
+    for (const kind of KINDS_WITH_META) {
+      expect(supportsVisibility(kind, V.visibility_private)).toBe(true);
+      expect(
+        supportsVisibility(kind, V.api_resource_visibility_unspecified),
+      ).toBe(true);
+    }
+  });
+
+  it("a blueprint kind holds org and platform", () => {
+    expect(supportsVisibility(ApiResourceKind.agent, V.visibility_org)).toBe(
+      true,
+    );
+    expect(
+      supportsVisibility(ApiResourceKind.agent, V.visibility_platform),
+    ).toBe(true);
+  });
+
+  it("an instance kind holds org but never platform (tenant isolation)", () => {
+    expect(
+      supportsVisibility(ApiResourceKind.agent_instance, V.visibility_org),
+    ).toBe(true);
+    expect(
+      supportsVisibility(ApiResourceKind.agent_instance, V.visibility_platform),
+    ).toBe(false);
+  });
+
+  it("an org-only kind holds org alone (environment: secrets never cross the org)", () => {
+    expect(
+      supportsVisibility(ApiResourceKind.environment, V.visibility_org),
+    ).toBe(true);
+    expect(
+      supportsVisibility(ApiResourceKind.environment, V.visibility_platform),
+    ).toBe(false);
+  });
+
+  it("a kind with no visibility config is private-only", () => {
+    expect(supportsVisibility(ApiResourceKind.session, V.visibility_org)).toBe(
+      false,
+    );
+    expect(
+      supportsVisibility(ApiResourceKind.session, V.visibility_platform),
+    ).toBe(false);
+  });
+});
+
+describe("supportedVisibilityLevels (the copy fragment)", () => {
+  it("names the levels that remain, private first, never the retired one", () => {
+    expect(supportedVisibilityLevels(ApiResourceKind.agent)).toBe(
+      "visibility_private, visibility_org, visibility_platform",
+    );
+    expect(supportedVisibilityLevels(ApiResourceKind.agent_instance)).toBe(
+      "visibility_private, visibility_org",
+    );
+    expect(supportedVisibilityLevels(ApiResourceKind.session)).toBe(
+      "visibility_private",
+    );
+    for (const kind of KINDS_WITH_META) {
+      expect(supportedVisibilityLevels(kind)).not.toContain(
+        "visibility_public",
+      );
+    }
+  });
+});

package/src/pipeline/apiresource-labels.ts

@@ -45,15 +45,16 @@ export const SYSTEM_MANAGED_LABEL = `${RESERVED_LABEL_PREFIX}system-managed`;
 
 /**
  * Marks system content: a resource the platform itself seeded rather than a
- * user authored — the system organization, the default agent, the
- * platform's own MCP servers. The label predates this module (the retired
- * seedpack wrote it on every row it applied; the official plugins' overlays
- * carry it on the resources they replace) and has one server-side meaning:
- * a plugin push may adopt a system-content row that holds a slug the plugin
- * needs, keeping the row's id and everything bound to it, instead of
- * refusing the slug as taken. It never marks a user's resource, so a user's
- * row is never adopted (domain/plugin/members.ts, judgeSlug). The CLI names
- * the same bytes as SYSTEM_ORG_LABEL for the organization it ensures.
+ * user authored. The retired seedpack wrote it on every row it applied, and
+ * CLIs before the bootstrap stopped labelling stamped it on the `stigmer`
+ * organization they created. A plugin overlay may still carry it on a
+ * member (a reserved label, so the push charges the platform permission for
+ * it). It has one server-side meaning: a plugin
+ * push may adopt a system-content row that holds a slug the plugin needs,
+ * keeping the row's id and everything bound to it, instead of refusing the
+ * slug as taken. It never marks a user's resource, so a user's row is never
+ * adopted (domain/plugin/members.ts, judgeSlug); on an organization it is
+ * inert.
  */
 export const SYSTEM_LABEL = `${RESERVED_LABEL_PREFIX}system`;
 

package/src/pipeline/apiresource-meta.ts

@@ -266,9 +266,18 @@ function tierRank(tier: ResourceTier): number {
 }
 
 /**
- * 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.
+ * 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.
  */
 export function supportsVisibility(
   kind: ApiResourceKind,
@@ -276,14 +285,19 @@ export function supportsVisibility(
 ): boolean {
   const config = getKindMeta(kind).authorization?.visibility;
   switch (visibility) {
-    case ApiResourceVisibility.visibility_public:
-      return config?.supportsPublic === true;
+    case ApiResourceVisibility.api_resource_visibility_unspecified:
+    case ApiResourceVisibility.visibility_private:
+      return true;
     case ApiResourceVisibility.visibility_org:
       return config?.supportsOrg === true;
     case ApiResourceVisibility.visibility_platform:
       return config?.supportsPlatform === true;
-    default:
-      return true;
+    case ApiResourceVisibility.visibility_public:
+      return false;
+    default: {
+      const exhaustive: never = visibility;
+      throw new Error(`unknown visibility level: ${String(exhaustive)}`);
+    }
   }
 }
 
@@ -298,9 +312,6 @@ 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";
   }