@stigmer/server 3.22.1-dev.20260922095755 → 3.23.0

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/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