@stigmer/server 3.22.1-dev.20260922095755 → 3.23.0

package/src/pipeline/steps/resolve-artifact-source.ts

@@ -8,18 +8,22 @@
  * are indistinguishable past this point.
  *
  * Skills carried this step alone (the Go ResolveArtifactSource port);
- * plugins are pushed the same two ways over the same upload slots (one
- * upload surface, as boot/compose.ts wires it), so the step lives
- * here and each kind names its lane-absent sentence and the request
- * fields it reads.
+ * plugins are pushed the same two ways over the same staging port (one
+ * upload surface, as boot/compose.ts wires it), so the step lives here
+ * and each kind names its lane-absent sentence and the request fields it
+ * reads. The staging port (domain/skill/transfer/staging.ts) hides which
+ * blob driver holds the bytes: the step never sees a slot or a bucket.
  *
  * The unusable-reference arm is INVALID_ARGUMENT, not a server fault: an
- * unknown, expired, already consumed, or minted-but-never-uploaded
- * reference all mean the client must re-mint and re-upload.
+ * unknown, expired, already consumed, or never-uploaded reference all mean
+ * the client must re-mint and re-upload. Any other failure reading the
+ * staged bytes is the driver's — an infrastructure fault the executor
+ * answers as a sanitized Internal, never dressed as the client's mistake.
  */
 import type { DescMessage, MessageShape } from "@bufbuild/protobuf";
 
-import type { UploadSlots } from "../../domain/skill/transfer/slots.js";
+import { SlotUnknownError } from "../../domain/skill/transfer/slots.js";
+import type { ArchiveStaging } from "../../domain/skill/transfer/staging.js";
 import { failedPreconditionError, invalidArgumentError } from "../errors.js";
 import type { PipelineStep } from "../pipeline.js";
 import type { RequestContext } from "../request-context.js";
@@ -38,7 +42,7 @@ export interface ArtifactSourceBinding<Desc extends DescMessage> {
 }
 
 export function newResolveArtifactSourceStep<Desc extends DescMessage>(
-  slots: UploadSlots | undefined,
+  staging: ArchiveStaging | undefined,
   binding: ArtifactSourceBinding<Desc>,
 ): PipelineStep<Desc> {
   return {
@@ -49,16 +53,19 @@ export function newResolveArtifactSourceStep<Desc extends DescMessage>(
         ctx.set(ARTIFACT_BYTES_KEY, artifact);
         return;
       }
-      if (slots === undefined) {
+      if (staging === undefined) {
         throw failedPreconditionError(binding.laneNotConfigured);
       }
       let data: Uint8Array;
       try {
-        data = await slots.consume(artifactUploadRef);
+        data = await staging.consume(artifactUploadRef);
       } catch (error) {
-        throw invalidArgumentError(
-          `artifact_upload_ref not usable: ${error instanceof Error ? error.message : String(error)} — request a new upload URL via createArtifactUploadUrl`,
-        );
+        if (error instanceof SlotUnknownError) {
+          throw invalidArgumentError(
+            `artifact_upload_ref not usable: ${error.message} — request a new upload URL via createArtifactUploadUrl`,
+          );
+        }
+        throw error;
       }
       ctx.set(ARTIFACT_BYTES_KEY, data);
     },

package/src/pipeline/steps/visibility-gates.ts

@@ -0,0 +1,174 @@
+/**
+ * The PUBLIC-visibility operator gates — the two write doors a resource
+ * can become public through, both consulting the ONE composed Authorizer
+ * with the same platform-scoped check (the Java
+ * PublicVisibilityEscalationPolicy port; C2 Stage 3, 20260827.10).
+ *
+ * PUBLIC is the only level that crosses every org boundary (one flip
+ * lists a resource in every tenant's cross-org catalog), so entering it
+ * is a curation decision: the owner requests, the platform team grants.
+ * The answer is `can_set_public_visibility` on `platform:stigmer` — a
+ * named operator capability, never a bare operator lookup.
+ *
+ *   - GuardPublicVisibility: the CREATE door, in the create chains of
+ *     the kinds whose VisibilityConfig supports PUBLIC (agent, workflow,
+ *     mcp_server, agent_instance, workflow_instance). After
+ *     BuildNewState — it inspects the state that will persist — which
+ *     keeps the pinned INVALID_ARGUMENT level-support rejections (the
+ *     earlier ValidateVisibility) their precedence over this
+ *     PERMISSION_DENIED.
+ *   - AuthorizeVisibilityTransition: the UPDATE door, in every
+ *     updateVisibility chain after ValidateVisibilityUpdate (the pinned
+ *     FAILED_PRECONDITION default-instance rejection keeps precedence,
+ *     the Java ordering the conformance suite depends on). Gates only
+ *     the ESCALATION to public (stored level is anything else).
+ *
+ * Both run LAZILY — only requests that actually involve the PUBLIC level
+ * reach the Authorizer — and both pass for internal callers (server-side
+ * flows publish platform resources by design). The OSS permissive
+ * default allows, so the local posture keeps today's behavior
+ * byte-identically; the cloud's FGA Authorizer supplies the gate.
+ *
+ * DELIBERATE partial port, recorded owner-visibly (Stage-3 execution
+ * record): Java's transition step additionally lets operators WITHOUT
+ * resource can_edit publish and take down (its updateVisibility chains
+ * authorize post-load, transition-aware); this edition's position-1
+ * Authorize enforces can_edit on updateVisibility before any step here
+ * runs, so those operator-without-edit lanes require can_edit until the
+ * Stage-4 chain disposition addresses them. No conformance lane pins
+ * them.
+ */
+import { Code, ConnectError } from "@connectrpc/connect";
+import type { DescMessage } from "@bufbuild/protobuf";
+
+import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import type { UpdateVisibilityInput } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
+import { IamPermission } from "@stigmer/protos/ai/stigmer/iam/v1/enum_pb";
+
+import type { Authorizer, AuthzDecision } from "../../extensions/authorizer.js";
+import type { CallerIdentity } from "../../extensions/identity.js";
+import { internalError } from "../errors.js";
+import type { PipelineStep } from "../pipeline.js";
+import type { RequestContext } from "../request-context.js";
+import { metadataOf } from "./shapes.js";
+
+/**
+ * The denial callers see at both doors (the Java policy copy verbatim).
+ * Deliberately not byte-pinned by the OSS conformance suite; the cloud
+ * gate itself is recorded via the clientPublicVisibilityWrites flag.
+ */
+export const PUBLIC_VISIBILITY_DENY_MESSAGE =
+  "Public visibility is granted by the platform team. " +
+  "Ask a platform operator to publish this resource.";
+
+/** The CREATE door: a new state declaring PUBLIC needs the operator grant. */
+export function newGuardPublicVisibilityStep<Desc extends DescMessage>(
+  authorizer: Authorizer,
+): PipelineStep<Desc> {
+  return {
+    name: "GuardPublicVisibility",
+    async execute(ctx: RequestContext<Desc>): Promise<void> {
+      if (ctx.callerIdentity.callerClass === "internal") {
+        return;
+      }
+      if (
+        metadataOf(ctx.newState)?.visibility !==
+        ApiResourceVisibility.visibility_public
+      ) {
+        return;
+      }
+      await requireOperatorMaySetPublic(authorizer, ctx.callerIdentity);
+    },
+  };
+}
+
+/**
+ * The UPDATE door: escalation to PUBLIC (the stored level is anything
+ * else) needs the operator grant. Reads the loaded target from the
+ * chain's own context key (every updateVisibility chain stores it —
+ * the RecordVisibilityBeforeUpdate pattern).
+ */
+export function newAuthorizeVisibilityTransitionStep<Desc extends DescMessage>(
+  targetKey: string,
+  authorizer: Authorizer,
+): PipelineStep<Desc> {
+  return {
+    name: "AuthorizeVisibilityTransition",
+    async execute(ctx: RequestContext<Desc>): Promise<void> {
+      if (ctx.callerIdentity.callerClass === "internal") {
+        return;
+      }
+      const requested = (ctx.input as unknown as UpdateVisibilityInput)
+        .visibility;
+      if (requested !== ApiResourceVisibility.visibility_public) {
+        return;
+      }
+      const target = ctx.get(targetKey);
+      if (target === undefined) {
+        // Wiring error, not a user error: without the loaded target there
+        // is no stored level, and a gate that silently passes un-guards
+        // the boundary it exists to protect.
+        throw internalError(
+          new Error(
+            "AuthorizeVisibilityTransition ran without a loaded target — step must be placed after the load step",
+          ),
+          "visibility authorization requires the loaded resource",
+        );
+      }
+      const stored = metadataOf(target as typeof ctx.newState)?.visibility;
+      if (stored === ApiResourceVisibility.visibility_public) {
+        return; // Re-asserting a stored PUBLIC is not an escalation.
+      }
+      await requireOperatorMaySetPublic(authorizer, ctx.callerIdentity);
+    },
+  };
+}
+
+/**
+ * The single owner of "may this caller set public?" — both doors call it,
+ * and so does the plugin push chain, whose requested level rides the
+ * request (the level then flows to every member through the members' own
+ * create and updateVisibility doors, which run this check again).
+ */
+export async function requireOperatorMaySetPublic(
+  authorizer: Authorizer,
+  caller: CallerIdentity,
+): Promise<void> {
+  let decision: AuthzDecision;
+  try {
+    decision = await authorizer.authorize(caller, {
+      permission: IamPermission.can_set_public_visibility,
+      resourceKind: ApiResourceKind.platform,
+      resourceId: "stigmer",
+    });
+  } catch (error) {
+    throw publicVisibilityCheckFailure(error);
+  }
+  switch (decision.kind) {
+    case "allow":
+      return;
+    case "deny":
+    case "not-found":
+      throw new ConnectError(
+        PUBLIC_VISIBILITY_DENY_MESSAGE,
+        Code.PermissionDenied,
+      );
+    case "unavailable":
+      throw publicVisibilityCheckFailure(decision.cause);
+    default: {
+      const exhaustive: never = decision;
+      throw publicVisibilityCheckFailure(
+        new Error(`unknown decision ${JSON.stringify(exhaustive)}`),
+      );
+    }
+  }
+}
+
+/** Authorization infrastructure failure: fail closed, sanitized (#478). */
+function publicVisibilityCheckFailure(error: unknown): ConnectError {
+  return internalError(
+    error instanceof Error ? error : new Error(String(error)),
+    "public-visibility authorization could not be completed",
+  );
+}

package/src/query/search/__tests__/criteria.test.ts

@@ -25,6 +25,8 @@ function criteria(overrides?: {
   kinds?: ApiResourceKind[];
   query?: string;
   org?: string;
+  excludePublic?: boolean;
+  crossOrgPublic?: boolean;
   pageNumber?: number;
   pageSize?: number;
 }): SearchCriteria {
@@ -32,6 +34,8 @@ function criteria(overrides?: {
     overrides?.kinds ?? [],
     overrides?.query ?? "",
     overrides?.org ?? "",
+    overrides?.excludePublic ?? false,
+    overrides?.crossOrgPublic ?? false,
     overrides?.pageNumber ?? 1,
     overrides?.pageSize ?? 20,
   );

package/src/query/search/__tests__/query-store.test.ts

@@ -3,8 +3,8 @@
  * sqlite_search_query_store_test.go (the kind-parsing table) and
  * sqlite_search_query_store_query_test.go (the end-to-end
  * write→index→query pins: session list mode, the #440 emptiness arm, the
- * #439 newly-searchable-kind arm), plus the scope filter (org strict:
- * visibility never widens or narrows it) and RebuildIndex —
+ * #439 newly-searchable-kind arm), plus the scope-filter matrix
+ * (org strict / crossOrgPublic / excludePublic) and RebuildIndex —
  * including the DD-D proof: rebuilding over an ADOPTED Go-created
  * database re-indexes the rows it already holds. The escaping and
  * score-normalization tables moved with their code into the sqlite
@@ -118,6 +118,8 @@ function criteria(overrides: {
   kinds?: ApiResourceKind[];
   query?: string;
   org?: string;
+  excludePublic?: boolean;
+  crossOrgPublic?: boolean;
   pageNumber?: number;
   pageSize?: number;
 }): SearchCriteria {
@@ -125,6 +127,8 @@ function criteria(overrides: {
     overrides.kinds ?? [],
     overrides.query ?? "",
     overrides.org ?? "",
+    overrides.excludePublic ?? false,
+    overrides.crossOrgPublic ?? false,
     overrides.pageNumber ?? 1,
     overrides.pageSize ?? 20,
   );
@@ -245,7 +249,7 @@ describe("write→index→query pins (Go's query_test.go)", () => {
   });
 });
 
-describe("scope filter (the org filter is strict)", () => {
+describe("scope-filter matrix (Go buildScopeFilter)", () => {
   beforeEach(async () => {
     await seed(
       ApiResourceKind.session,
@@ -265,10 +269,10 @@ describe("scope filter (the org filter is strict)", () => {
     );
     await seed(
       ApiResourceKind.session,
-      "ses-b-org",
+      "ses-b-public",
       SessionSchema,
-      newSession("ses-b-org", "org-b", "b org", {
-        visibility: ApiResourceVisibility.visibility_org,
+      newSession("ses-b-public", "org-b", "b public", {
+        visibility: ApiResourceVisibility.visibility_public,
         createdAtSeconds: 1_700_000_001,
       }),
     );
@@ -284,15 +288,38 @@ describe("scope filter (the org filter is strict)", () => {
     expect(ids(result)).toEqual(["ses-a-private"]);
   });
 
-  it("another org's rows stay out of an org filter whatever their visibility", async () => {
+  it("crossOrgPublic widens to OTHER orgs' public rows only", async () => {
     const result = await queryStore.search(
-      criteria({ kinds: [ApiResourceKind.session], org: "org-b" }),
+      criteria({
+        kinds: [ApiResourceKind.session],
+        org: "org-a",
+        crossOrgPublic: true,
+      }),
     );
     expect(new Set(ids(result))).toEqual(
-      new Set(["ses-b-private", "ses-b-org"]),
+      new Set(["ses-a-private", "ses-b-public"]),
     );
   });
 
+  it("excludePublic subtracts public rows from any scope", async () => {
+    const unscoped = await queryStore.search(
+      criteria({ kinds: [ApiResourceKind.session], excludePublic: true }),
+    );
+    expect(new Set(ids(unscoped))).toEqual(
+      new Set(["ses-a-private", "ses-b-private"]),
+    );
+
+    const widened = await queryStore.search(
+      criteria({
+        kinds: [ApiResourceKind.session],
+        org: "org-a",
+        crossOrgPublic: true,
+        excludePublic: true,
+      }),
+    );
+    expect(ids(widened)).toEqual(["ses-a-private"]);
+  });
+
   it("no org filter returns every row, newest first (list mode ordering)", async () => {
     const result = await queryStore.search(
       criteria({ kinds: [ApiResourceKind.session] }),
@@ -300,7 +327,7 @@ describe("scope filter (the org filter is strict)", () => {
     expect(ids(result)).toEqual([
       "ses-a-private",
       "ses-b-private",
-      "ses-b-org",
+      "ses-b-public",
     ]);
   });
 });
@@ -447,7 +474,9 @@ describe("rebuildIndex", () => {
         "skl_1",
         SkillSchema,
       );
-      expect(toBinary(SkillSchema, raw)).toEqual(toBinary(SkillSchema, skill));
+      expect(toBinary(SkillSchema, raw)).toEqual(
+        toBinary(SkillSchema, skill),
+      );
     } finally {
       await adopted.close();
       fixture.cleanup();

package/src/query/search/controller.ts

@@ -61,6 +61,7 @@ async function search(
     kinds: request.kinds.map((kind) => ApiResourceKind[kind] ?? String(kind)),
     query: request.query,
     org: request.org,
+    exclude_public: request.excludePublic,
   });
 
   try {

package/src/query/search/criteria.ts

@@ -98,6 +98,8 @@ export class SearchCriteria {
     private readonly requestedKinds: readonly ApiResourceKind[],
     private readonly queryText: string,
     private readonly orgFilterValue: string,
+    private readonly excludePublicFlag: boolean,
+    private readonly crossOrgPublicFlag: boolean,
     private readonly pageNumberValue: number,
     private readonly pageSizeValue: number,
   ) {}
@@ -119,6 +121,8 @@ export class SearchCriteria {
     kinds: readonly ApiResourceKind[],
     query: string,
     orgFilter: string,
+    excludePublic: boolean,
+    crossOrgPublic: boolean,
     pageNumber: number,
     pageSize: number,
   ): SearchCriteria {
@@ -132,6 +136,8 @@ export class SearchCriteria {
       [...kinds],
       normalizedQuery,
       goTrimSpace(orgFilter),
+      excludePublic,
+      crossOrgPublic,
       pageNumber < 1 ? 1 : pageNumber,
       pageSize < 1 ? DEFAULT_PAGE_SIZE : Math.min(pageSize, MAX_PAGE_SIZE),
     );
@@ -150,6 +156,14 @@ export class SearchCriteria {
     return this.orgFilterValue;
   }
 
+  excludePublic(): boolean {
+    return this.excludePublicFlag;
+  }
+
+  crossOrgPublic(): boolean {
+    return this.crossOrgPublicFlag;
+  }
+
   pageNumber(): number {
     return this.pageNumberValue;
   }

package/src/query/search/handler.ts

@@ -52,11 +52,10 @@ export class SearchHandler {
    * mapping string-matches them (#478 sanitization contract).
    *
    * With a composed ListReadScope (20260830.01, census lane 21) the
-   * store read ALWAYS carries a per-effective-kind authorized-id map —
-   * the Java SearchHandler's QueryAuthorizedIds step. There is no request
-   * shape that skips the scope: the one that did (the retired public
-   * level's cross-organization discovery, which the engine filtered by
-   * visibility with FGA never consulted) left with the level. A scope
+   * store read carries a per-effective-kind authorized-id map — the Java
+   * SearchHandler's QueryAuthorizedIds step, with its crossOrgPublic
+   * bypass preserved verbatim (public-widened discovery is
+   * visibility-filtered by the engine, FGA never consulted). A scope
    * failure propagates — the controller's default arm answers the
    * sanitized Internal, never a silently unscoped result.
    */
@@ -75,6 +74,8 @@ export class SearchHandler {
         request.kinds,
         request.query,
         request.org,
+        request.excludePublic,
+        request.crossOrgPublic,
         request.page?.num ?? 0,
         request.page?.size ?? 0,
       );
@@ -86,7 +87,7 @@ export class SearchHandler {
     }
 
     let authorizedIdsByKind: Map<string, ReadonlySet<string>> | undefined;
-    if (this.listReadScope !== undefined) {
+    if (this.listReadScope !== undefined && !criteria.crossOrgPublic()) {
       authorizedIdsByKind = new Map<string, ReadonlySet<string>>();
       for (const kind of criteria.effectiveKinds()) {
         authorizedIdsByKind.set(

package/src/query/search/query-store.ts

@@ -81,6 +81,8 @@ export class SqliteSearchQueryStore implements SearchQueryStore {
         // is already goTrimSpace'd). Engine syntax is the driver's job.
         terms: criteria.hasQuery() ? goFields(criteria.query()) : undefined,
         orgFilter: criteria.orgFilter(),
+        crossOrgPublic: criteria.crossOrgPublic(),
+        excludePublic: criteria.excludePublic(),
         limit: criteria.pageSize(),
         offset: criteria.offset(),
       });

package/src/store/__tests__/store-contract.ts

@@ -934,6 +934,8 @@ export function describeStoreContract(
         kinds: ["agent"],
         terms: ["kubernetes"],
         orgFilter: "",
+        crossOrgPublic: false,
+        excludePublic: false,
         limit: 20,
         offset: 0,
       });
@@ -957,6 +959,8 @@ export function describeStoreContract(
         kinds: ["agent"],
         terms: ["kuber"],
         orgFilter: "",
+        crossOrgPublic: false,
+        excludePublic: false,
         limit: 20,
         offset: 0,
       });
@@ -966,6 +970,8 @@ export function describeStoreContract(
         kinds: ["agent"],
         terms: ["kubernetes", "deployment"],
         orgFilter: "",
+        crossOrgPublic: false,
+        excludePublic: false,
         limit: 20,
         offset: 0,
       });
@@ -975,6 +981,8 @@ export function describeStoreContract(
         kinds: ["agent"],
         terms: ["kubernetes", "absent"],
         orgFilter: "",
+        crossOrgPublic: false,
+        excludePublic: false,
         limit: 20,
         offset: 0,
       });
@@ -1000,6 +1008,8 @@ export function describeStoreContract(
         kinds: ["agent"],
         terms: ["NEAR", "plain"],
         orgFilter: "",
+        crossOrgPublic: false,
+        excludePublic: false,
         limit: 20,
         offset: 0,
       });
@@ -1029,6 +1039,8 @@ export function describeStoreContract(
         kinds: ["agent", "workflow"],
         terms: ["scoped"],
         orgFilter: "",
+        crossOrgPublic: false,
+        excludePublic: false,
         authorizedIdsByKind: new Map([["agent", new Set(["agt-mine"])]]),
         limit: 20,
         offset: 0,
@@ -1044,6 +1056,8 @@ export function describeStoreContract(
         kinds: ["agent", "workflow"],
         terms: ["scoped"],
         orgFilter: "",
+        crossOrgPublic: false,
+        excludePublic: false,
         authorizedIdsByKind: new Map([
           ["agent", new Set<string>()],
           ["workflow", new Set(["wfl-any"])],
@@ -1058,6 +1072,8 @@ export function describeStoreContract(
         kinds: ["agent", "workflow"],
         terms: ["scoped"],
         orgFilter: "",
+        crossOrgPublic: false,
+        excludePublic: false,
         authorizedIdsByKind: new Map([
           ["agent", new Set<string>()],
           ["workflow", new Set<string>()],
@@ -1073,13 +1089,15 @@ export function describeStoreContract(
         kinds: ["agent", "workflow"],
         terms: ["scoped"],
         orgFilter: "",
+        crossOrgPublic: false,
+        excludePublic: false,
         limit: 20,
         offset: 0,
       });
       expect(unscoped.totalCount).toBe(3);
     });
 
-    it("org scoping is strict: the visibility column never widens or narrows the org filter", async () => {
+    it("org scoping: strict filter, cross-org public widening, and the public subtraction", async () => {
       await fx.store.upsertSearchIndex(
         ApiResourceKind.agent,
         "agt-mine",
@@ -1087,11 +1105,11 @@ export function describeStoreContract(
       );
       await fx.store.upsertSearchIndex(
         ApiResourceKind.agent,
-        "agt-platform",
+        "agt-public",
         entry({
           name: "searchable beta",
           org: "globex",
-          visibility: "visibility_platform",
+          visibility: "visibility_public",
         }),
       );
       await fx.store.upsertSearchIndex(
@@ -1104,20 +1122,37 @@ export function describeStoreContract(
         kinds: ["agent"],
         terms: ["searchable"],
         orgFilter: "acme",
+        crossOrgPublic: false,
+        excludePublic: false,
         limit: 20,
         offset: 0,
       });
       expect(strict.hits.map((hit) => hit.resourceId)).toEqual(["agt-mine"]);
 
-      const unscoped = await fx.store.querySearchIndex({
+      const widened = await fx.store.querySearchIndex({
+        kinds: ["agent"],
+        terms: ["searchable"],
+        orgFilter: "acme",
+        crossOrgPublic: true,
+        excludePublic: false,
+        limit: 20,
+        offset: 0,
+      });
+      expect(new Set(widened.hits.map((hit) => hit.resourceId))).toEqual(
+        new Set(["agt-mine", "agt-public"]),
+      );
+
+      const noPublic = await fx.store.querySearchIndex({
         kinds: ["agent"],
         terms: ["searchable"],
         orgFilter: "",
+        crossOrgPublic: false,
+        excludePublic: true,
         limit: 20,
         offset: 0,
       });
-      expect(new Set(unscoped.hits.map((hit) => hit.resourceId))).toEqual(
-        new Set(["agt-mine", "agt-platform", "agt-foreign"]),
+      expect(new Set(noPublic.hits.map((hit) => hit.resourceId))).toEqual(
+        new Set(["agt-mine", "agt-foreign"]),
       );
     });
 
@@ -1137,6 +1172,8 @@ export function describeStoreContract(
         kinds: ["agent"],
         terms: undefined,
         orgFilter: "",
+        crossOrgPublic: false,
+        excludePublic: false,
         limit: 20,
         offset: 0,
       });
@@ -1166,6 +1203,8 @@ export function describeStoreContract(
         kinds: ["organization"],
         terms: ["original"],
         orgFilter: "",
+        crossOrgPublic: false,
+        excludePublic: false,
         limit: 20,
         offset: 0,
       });
@@ -1175,6 +1214,8 @@ export function describeStoreContract(
         kinds: ["organization"],
         terms: ["renamed"],
         orgFilter: "",
+        crossOrgPublic: false,
+        excludePublic: false,
         limit: 20,
         offset: 0,
       });
@@ -1185,6 +1226,8 @@ export function describeStoreContract(
         kinds: ["organization"],
         terms: undefined,
         orgFilter: "",
+        crossOrgPublic: false,
+        excludePublic: false,
         limit: 20,
         offset: 0,
       });
@@ -1200,6 +1243,8 @@ export function describeStoreContract(
         kinds: ["organization"],
         terms: undefined,
         orgFilter: "",
+        crossOrgPublic: false,
+        excludePublic: false,
         limit: 20,
         offset: 0,
       });

package/src/store/interface.ts

@@ -135,9 +135,8 @@ export interface SearchIndexEntry {
   /** Owning org (metadata.org) — org-scoped filtering. */
   readonly org: string;
   /**
-   * Visibility enum NAME (e.g. "visibility_org"), carried for display;
-   * scope filtering is by org and by the authorized-id map, never by
-   * this column.
+   * Visibility enum NAME (e.g. "visibility_public"); scope filtering only
+   * special-cases "visibility_public", all other levels are org-scoped.
    */
   readonly visibility: string;
   /** Unix seconds creation time — sorting in list mode (no query). */
@@ -167,6 +166,10 @@ export interface SearchIndexQuery {
   readonly terms: readonly string[] | undefined;
   /** Org scope; "" = no org filter. */
   readonly orgFilter: string;
+  /** With orgFilter: also admit visibility_public rows from ANY org. */
+  readonly crossOrgPublic: boolean;
+  /** Independent subtraction: drop visibility_public rows from any scope. */
+  readonly excludePublic: boolean;
   /**
    * Optional per-kind authorized-id allowlist (kind NAME → ids) — the
    * multi-tenant list-read scoping arm (20260830.01): a listed kind