@stigmer/server 3.39.0 → 3.40.0

package/src/domain/agentexecution/create-steps.ts

@@ -34,6 +34,7 @@ import type { Session } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_
 import { SessionSchema } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
 import type { SessionSpec } from "@stigmer/protos/ai/stigmer/agentic/session/v1/spec_pb";
 import { SessionSpecSchema } from "@stigmer/protos/ai/stigmer/agentic/session/v1/spec_pb";
+import type { IdentityAccount } from "@stigmer/protos/ai/stigmer/iam/identityaccount/v1/api_pb";
 import type { Organization } from "@stigmer/protos/ai/stigmer/tenancy/organization/v1/api_pb";
 import { OrganizationSchema } from "@stigmer/protos/ai/stigmer/tenancy/organization/v1/api_pb";
 import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
@@ -41,6 +42,7 @@ import { clone } from "@bufbuild/protobuf";
 
 import type { Logger } from "../../boot/logger.js";
 import type { CallerIdentity } from "../../extensions/identity.js";
+import { isFirstPartyHumanOperator } from "../../extensions/identity.js";
 import type { ResourceAuthorizationLifecycle } from "../../extensions/resource-authorization.js";
 import { notifyDefaultInstanceLinked } from "../../pipeline/steps/authorization-tuples.js";
 import {
@@ -53,9 +55,12 @@ import {
 } from "../../pipeline/errors.js";
 import { ConnectError } from "@connectrpc/connect";
 import type { PipelineStep } from "../../pipeline/pipeline.js";
+import type { RequestContext } from "../../pipeline/request-context.js";
 import { ResourceNotFoundError } from "../../store/interface.js";
 import type { Store } from "../../store/interface.js";
 import { buildDefaultInstanceRequest } from "../agentinstance/defaultinstance.js";
+import type { AccountsByCaller } from "../identityaccount/resolve.js";
+import { accountForCaller } from "../identityaccount/resolve.js";
 
 import type { AgentExecutionStatusObserver } from "../../extensions/status-hooks.js";
 
@@ -416,19 +421,27 @@ export function newCreateSessionIfNeededStep(deps: {
 // ---------------------------------------------------------------------------
 
 /**
- * Snapshots the organization's declared standing context onto the
- * execution spec (DD-002, stigmer/stigmer#293). SERVER-OWNED: stamped
- * unconditionally, overwriting anything the caller supplied. OSS composes
- * org_context only (the local server has no per-request user identity).
- * BEST-EFFORT: an execution must never fail to start because its optional
- * preferences could not load — genuine failures log at ERROR (quiet
- * degradation of a should-work path must stay visible) and degrade to an
- * empty snapshot. Snapshot-at-create is the point: preferences are
+ * Snapshots the declared standing context onto the execution spec
+ * (DD-002, stigmer/stigmer#293). SERVER-OWNED: stamped unconditionally,
+ * overwriting anything the caller supplied. Two independent halves:
+ * org_context, the organization's, for every run; and user_context, the
+ * run's person's own (stigmer#1397) — composed only where callers are
+ * persons (`personAccounts`, the require-authentication posture) and only
+ * for a first-party human operator (runPersonOf), as the Java step did.
+ * The single-operator posture composes org_context alone: its one
+ * operator's context is the organization's. The org half deliberately
+ * keeps running for every lane (schedule and channel runs carry the
+ * organization's instructions today); only the person's half is about a
+ * person. BEST-EFFORT: an execution must never fail to start because its
+ * optional preferences could not load — genuine failures log at ERROR
+ * (quiet degradation of a should-work path must stay visible) and degrade
+ * that half to empty. Snapshot-at-create is the point: preferences are
  * mutable, executions are immutable audit records.
  */
 export function newComposeDeclaredPreferencesStep(
   store: Store,
   logger: Logger,
+  personAccounts?: AccountsByCaller,
 ): PipelineStep<CreateDesc> {
   return {
     name: "ComposeDeclaredPreferences",
@@ -438,50 +451,103 @@ export function newComposeDeclaredPreferencesStep(
       // Claim the server-owned field first, before any load can fail.
       execution.spec.declaredPreferences = create(DeclaredPreferencesSchema);
 
-      let orgId = execution.metadata?.org ?? "";
-      if (orgId === "") {
-        orgId = ctx.input.metadata?.org ?? "";
-      }
-      if (orgId === "") {
-        logger.debug(
-          "No org on execution metadata, composing no declared preferences",
-        );
-        return;
-      }
-
-      let org: Organization;
-      try {
-        org = await store.getResource(
-          ApiResourceKind.organization,
-          orgId,
-          OrganizationSchema,
-        );
-      } catch (error) {
-        if (error instanceof ResourceNotFoundError) {
-          logger.debug(
-            "Org not found in store, composing no declared preferences",
-            { orgId },
-          );
-          return;
-        }
-        logger.error(
-          "Failed to load org for declared preferences - degrading to none (best-effort contract)",
-          {
-            orgId,
-            error: error instanceof Error ? error.message : String(error),
-          },
-        );
-        return;
-      }
-
       // Verbatim per DD-002 D2: the server stamps content only;
       // blank-is-absent is the runner's read-side convention.
       execution.spec.declaredPreferences.orgContext =
-        org.spec?.preferences?.standingContext ?? "";
+        await loadOrgStandingContext(store, logger, orgIdOf(ctx));
+
+      if (personAccounts === undefined) {
+        return;
+      }
+      const person = await runPersonOf(
+        personAccounts,
+        ctx.callerIdentity,
+        logger,
+        "Failed to load the run's person for declared preferences - degrading user context to none (best-effort contract)",
+      );
+      execution.spec.declaredPreferences.userContext =
+        person?.spec?.preferences?.standingContext ?? "";
     },
   };
 }
 
+/** The org a create addresses: the execution's metadata, else the input's. */
+function orgIdOf(ctx: RequestContext<CreateDesc>): string {
+  const orgId = ctx.newState.metadata?.org ?? "";
+  return orgId !== "" ? orgId : (ctx.input.metadata?.org ?? "");
+}
+
+/** The organization's standing context, best-effort ("" on every degrade). */
+async function loadOrgStandingContext(
+  store: Store,
+  logger: Logger,
+  orgId: string,
+): Promise<string> {
+  if (orgId === "") {
+    logger.debug(
+      "No org on execution metadata, composing no declared preferences",
+    );
+    return "";
+  }
+
+  let org: Organization;
+  try {
+    org = await store.getResource(
+      ApiResourceKind.organization,
+      orgId,
+      OrganizationSchema,
+    );
+  } catch (error) {
+    if (error instanceof ResourceNotFoundError) {
+      logger.debug(
+        "Org not found in store, composing no declared preferences",
+        {
+          orgId,
+        },
+      );
+      return "";
+    }
+    logger.error(
+      "Failed to load org for declared preferences - degrading to none (best-effort contract)",
+      {
+        orgId,
+        error: error instanceof Error ? error.message : String(error),
+      },
+    );
+    return "";
+  }
+  return org.spec?.preferences?.standingContext ?? "";
+}
+
+/**
+ * The person a run is created by, where callers are persons
+ * (stigmer#1387): the account a first-party human operator stands for
+ * (extensions/identity.ts states who that is, once). `undefined` for every
+ * other lane — runner, schedule, channel, guest, machine, a PlatformClient
+ * token, anything server-composed — for a caller no account stands for,
+ * and, best-effort, on a store fault (logged at ERROR with the caller's
+ * copy: the compose steps degrade, they never fail a create).
+ */
+async function runPersonOf(
+  personAccounts: AccountsByCaller,
+  caller: CallerIdentity,
+  logger: Logger,
+  faultMessage: string,
+): Promise<IdentityAccount | undefined> {
+  if (!isFirstPartyHumanOperator(caller)) {
+    return undefined;
+  }
+  try {
+    return await accountForCaller(personAccounts, caller);
+  } catch (error) {
+    logger.error(faultMessage, {
+      identityId: caller.identityId,
+      error: error instanceof Error ? error.message : String(error),
+    });
+    return undefined;
+  }
+}
+
 // ---------------------------------------------------------------------------
 // ComposeRecalledMemories — compose_recalled_memories_step.go.
 // ---------------------------------------------------------------------------
@@ -492,18 +558,25 @@ export function newComposeDeclaredPreferencesStep(
  * memory loop, sibling of ComposeDeclaredPreferences in every invariant:
  * server-owned (enabled=false stamped on every ineligible/degraded path),
  * best-effort (degrading to DISABLED, never enabled-with-zero-facts, so a
- * broken recall never falsely offers the remember tool). OSS gates on the
- * org flag alone with the empty-string subject sentinel; confirmed-only
+ * broken recall never falsely offers the remember tool); confirmed-only
  * (the consent gate is meaningless otherwise); no compose-time truncation
  * (the runner's retriever selects at prompt build, recorded on
  * status.recalled_memories_report). Facts order oldest-first on
- * created_at — identical prompt order in both editions. The Organization
- * is loaded independently of the preferences step: step independence over
- * one saved read.
+ * created_at — identical prompt order in every posture.
+ *
+ * WHOSE memories follows the posture (stigmer#1387, the Java step's
+ * gates in its order): where callers are persons (`personAccounts`) the
+ * run must be created by a first-party human operator (runPersonOf), the
+ * organization's memory_enabled must be on, then that person's own — and
+ * the snapshot is that person's confirmed facts in the organization. The
+ * single-operator posture gates on the org flag alone with the
+ * empty-string subject sentinel. The Organization is loaded independently
+ * of the preferences step: step independence over one saved read.
  */
 export function newComposeRecalledMemoriesStep(
   store: Store,
   logger: Logger,
+  personAccounts?: AccountsByCaller,
 ): PipelineStep<CreateDesc> {
   return {
     name: "ComposeRecalledMemories",
@@ -513,16 +586,21 @@ export function newComposeRecalledMemoriesStep(
       // Claim the server-owned field first.
       execution.spec.recalledMemories = create(RecalledMemoriesSchema);
 
-      let orgId = execution.metadata?.org ?? "";
-      if (orgId === "") {
-        orgId = ctx.input.metadata?.org ?? "";
-      }
+      const orgId = orgIdOf(ctx);
       if (orgId === "") {
         logger.debug(
           "No org on execution metadata, composing no recalled memories",
         );
         return;
       }
+      // Only a person's own run recalls (the Java gate order: the caller
+      // first, before any read).
+      if (
+        personAccounts !== undefined &&
+        !isFirstPartyHumanOperator(ctx.callerIdentity)
+      ) {
+        return;
+      }
 
       let org: Organization;
       try {
@@ -555,9 +633,27 @@ export function newComposeRecalledMemoriesStep(
         return;
       }
 
+      // The subject whose facts are recalled: the run's person, whose own
+      // switch must be on too, or the single-operator sentinel.
+      let subject = "";
+      if (personAccounts !== undefined) {
+        const person = await runPersonOf(
+          personAccounts,
+          ctx.callerIdentity,
+          logger,
+          "Failed to load the run's person for recalled memories - degrading to disabled (best-effort contract)",
+        );
+        if (person?.spec?.preferences?.memoryEnabled !== true) {
+          // A person who has not opted in is normal operation, not
+          // degradation; no log.
+          return;
+        }
+        subject = person.metadata?.id ?? "";
+      }
+
       let facts;
       try {
-        facts = await loadConfirmedFacts(store, orgId);
+        facts = await loadConfirmedFacts(store, orgId, subject);
       } catch (error) {
         // Enabled stays false: a broken recall must not offer the
         // remember tool (the enabled bit doubles as the tool signal).
@@ -582,13 +678,17 @@ export function newComposeRecalledMemoriesStep(
 }
 
 /**
- * Scans the memory kind for the OSS single-user subject's (the ""
- * sentinel) confirmed records in the org, oldest-first. Facts carry only
- * memory_id + content (the id is the transparency link back to the
- * addressable record). Undecodable rows are skipped — one bad record must
- * not take recall down.
+ * Scans the memory kind for `subject`'s confirmed records in the org,
+ * oldest-first — the run's person's account id, or the single-operator
+ * "" sentinel. Facts carry only memory_id + content (the id is the
+ * transparency link back to the addressable record). Undecodable rows are
+ * skipped — one bad record must not take recall down.
  */
-async function loadConfirmedFacts(store: Store, orgId: string) {
+async function loadConfirmedFacts(
+  store: Store,
+  orgId: string,
+  subject: string,
+) {
   const rows = await store.listResources(ApiResourceKind.memory);
   const memories: Memory[] = [];
   for (const data of rows) {
@@ -601,7 +701,7 @@ async function loadConfirmedFacts(store: Store, orgId: string) {
     if ((memory.metadata?.org ?? "") !== orgId) {
       continue;
     }
-    if ((memory.spec?.subjectIdentityAccountId ?? "") !== "") {
+    if ((memory.spec?.subjectIdentityAccountId ?? "") !== subject) {
       continue;
     }
     if (

package/src/domain/agentinstance/__tests__/store-faults.test.ts

@@ -1,23 +1,30 @@
 /**
- * Pins the store-fault contract of the agent instance's visibility-update
- * load: a typed ResourceNotFoundError answers NotFound with the domain's
- * pinned copy (`agent instance not found: <id>`), and any other store failure
- * is an infrastructure fault answered as a sanitized Internal, never a
- * NotFound that tells a client the instance does not exist
- * (stigmer/stigmer#1345).
+ * Pins the store-fault contract of the agent instance's two loads. The
+ * visibility-update load: a typed ResourceNotFoundError answers NotFound with
+ * the domain's pinned copy (`agent instance not found: <id>`), and any other
+ * store failure is an infrastructure fault answered as a sanitized Internal,
+ * never a NotFound that tells a client the instance does not exist
+ * (stigmer/stigmer#1345). Create's parent-agent load reads the agent through
+ * the in-process query client, so the store's typed miss arrives as a Connect
+ * NotFound: that answers the pinned `Agent not found: <id>`, and any other
+ * failure an Internal, never a missing parent (stigmer/stigmer#1351).
  *
- * The surface is updateVisibility, reached through the registered handler on
- * an in-process router. The composed suites reach only a real store, which
- * cannot fail selectively, so it runs here against a store whose read throws.
- * The parent-agent loader is untouchable: a load that fails must stop the
- * call before anything past it runs.
+ * Both surfaces are reached through the registered handler on an in-process
+ * router. The composed suites reach only a real store, which cannot fail
+ * selectively, so the visibility update runs against a store whose read
+ * throws and create against a parent loader whose read throws. Whatever the
+ * surface does not need is untouchable: a load that fails must stop the call
+ * before anything past it runs.
  *
- * Out of scope: the NotFound copy itself (wire contract) and create's
- * parent-agent load, which folds every RPC error into NotFound
- * (stigmer/stigmer#1351).
+ * Out of scope: the NotFound copies themselves (wire contract).
  */
-import type { Client, ConnectError } from "@connectrpc/connect";
-import { Code, createClient, createRouterTransport } from "@connectrpc/connect";
+import type { Client } from "@connectrpc/connect";
+import {
+  Code,
+  ConnectError,
+  createClient,
+  createRouterTransport,
+} from "@connectrpc/connect";
 import { describe, expect, it } from "vitest";
 
 import { AgentInstanceCommandController } from "@stigmer/protos/ai/stigmer/agentic/agentinstance/v1/command_pb";
@@ -31,11 +38,13 @@ import {
   failingStore,
   untouchable,
 } from "../../../pipeline/__tests__/support.js";
+import { INTERNAL_FALLBACK_MESSAGE } from "../../../pipeline/pipeline.js";
 import { newPermissiveSingleTeamAuthorizer } from "../../../pipeline/steps/authorize.js";
 import { ResourceNotFoundError } from "../../../store/interface.js";
 import type { Store } from "../../../store/interface.js";
 
 import { registerAgentInstanceServices } from "../controller.js";
+import type { ParentAgentLoaderProvider } from "../steps.js";
 
 const silentLogger = createLogger({
   level: "error",
@@ -44,22 +53,34 @@ const silentLogger = createLogger({
 });
 
 const INSTANCE_ID = "ain_storefault";
+const AGENT_ID = "agt_storefault";
 
 const NOT_FOUND_COPY = `agent instance not found: ${INSTANCE_ID}`;
 const LOAD_FAULT_COPY = "failed to load agent instance";
+const PARENT_NOT_FOUND_COPY = `Agent not found: ${AGENT_ID}`;
+const PARENT_LOAD_FAULT_COPY = "failed to load parent agent";
 
 const MISSING = (): Error =>
   new ResourceNotFoundError(`agent_instance/${INSTANCE_ID}`);
 const LOCKED = (): Error => new Error("SQLITE_BUSY: database is locked");
 
+/** What the agent query's `get` answers for a missing and a faulted agent. */
+const PARENT_MISSING = (): Error =>
+  new ConnectError(`Agent not found: ${AGENT_ID}`, Code.NotFound);
+const PARENT_FAULTED = (): Error =>
+  new ConnectError(INTERNAL_FALLBACK_MESSAGE, Code.Internal);
+
 /**
  * The registered handlers on an in-process router: the verifier chain stamps
  * the trusted-local caller and the apiresource interceptor the kind, then
  * Authorize and ValidateProto run and the load is the first step that reads
- * the store.
+ * the store or the parent.
  */
 function instanceCommand(
   store: Store,
+  parentAgentLoader: ParentAgentLoaderProvider = untouchable(
+    "parentAgentLoader",
+  ),
 ): Client<typeof AgentInstanceCommandController> {
   const transport = createRouterTransport(
     (router) => {
@@ -68,7 +89,7 @@ function instanceCommand(
         logger: silentLogger,
         authorizer: newPermissiveSingleTeamAuthorizer(),
         authorizationLifecycle: undefined,
-        parentAgentLoader: untouchable("parentAgentLoader"),
+        parentAgentLoader,
         listReadScope: undefined,
       });
     },
@@ -108,3 +129,33 @@ describe("updateVisibility — LoadInstanceForVisibilityUpdate", () => {
     expect(error.rawMessage).toBe(LOAD_FAULT_COPY);
   });
 });
+
+describe("create — LoadParentAgent", () => {
+  function surfaceError(parentError: Error): Promise<ConnectError> {
+    const failingParent: ParentAgentLoaderProvider = () => ({
+      get: () => Promise.reject(parentError),
+    });
+    return errorOf(() =>
+      instanceCommand(untouchable("store"), failingParent).create({
+        apiVersion: "agentic.stigmer.ai/v1",
+        kind: "AgentInstance",
+        metadata: { name: "Store Fault Instance", org: "org_storefault" },
+        spec: { agentId: AGENT_ID },
+      }),
+    );
+  }
+
+  it("a missing parent agent answers NotFound with the pinned copy", async () => {
+    const error = await surfaceError(PARENT_MISSING());
+
+    expect(error.code).toBe(Code.NotFound);
+    expect(error.rawMessage).toBe(PARENT_NOT_FOUND_COPY);
+  });
+
+  it("any other parent-load failure answers a sanitized Internal", async () => {
+    const error = await surfaceError(PARENT_FAULTED());
+
+    expect(error.code).toBe(Code.Internal);
+    expect(error.rawMessage).toBe(PARENT_LOAD_FAULT_COPY);
+  });
+});

package/src/domain/agentinstance/controller.ts

@@ -10,8 +10,14 @@
  * Proven by agentinstance.conformance.test.ts (CONFORMANCE_TARGET=local),
  * __tests__/agentinstance.test.ts and __tests__/store-faults.test.ts.
  *
- * Versus Stigmer Cloud, OSS excludes the CreateIamPolicies and Publish
- * steps. Deliberately NO same-org rule on create, unlike WorkflowInstance:
+ * Every chain opens with Authorize, and create asks
+ * can_create_agent_instance on the organization, then can_create_instance
+ * on the parent agent (AuthorizeResolvedTarget); create, delete and
+ * updateVisibility run the shared tuple-lifecycle steps against the
+ * composed lifecycle; getByAgent and list narrow through the composed list
+ * read scope (docs/authorization-coverage.md §7).
+ *
+ * Deliberately NO same-org rule on create, unlike WorkflowInstance:
  * an agent is a shareable blueprint, and one agent legitimately has
  * instances in several orgs (the marketplace case). What governs a
  * cross-org instance in both editions is the create lane's authorization

package/src/domain/agentinstance/steps.ts

@@ -6,6 +6,7 @@
  * contracts: the parent-agent edge, the immutable agent_id, the
  * default-instance visibility guard, and the org/label list filters.
  */
+import { Code, ConnectError } from "@connectrpc/connect";
 import { create, fromBinary } from "@bufbuild/protobuf";
 import type { DescMessage } from "@bufbuild/protobuf";
 
@@ -69,7 +70,9 @@ export const PARENT_AGENT_KEY = "parent_agent";
  * an agent is a shareable blueprint and one agent legitimately has
  * instances in several orgs (the marketplace case) — the instance's
  * organization is the caller's, and the check below asks the caller's
- * standing there.
+ * standing there. The agent is read through the in-process query client, so
+ * a missing one arrives as a Connect NotFound; any other failure is a fault
+ * answered as Internal, never a missing parent.
  */
 export function newLoadParentAgentStep(
   agentLoader: ParentAgentLoaderProvider,
@@ -88,11 +91,14 @@ export function newLoadParentAgentStep(
       try {
         parentAgent = await agentLoader().get(agentId);
       } catch (error) {
-        logger.warn("Parent agent not found", {
-          agentId,
-          error: error instanceof Error ? error.message : String(error),
-        });
-        throw notFoundError("Agent", agentId);
+        if (error instanceof ConnectError && error.code === Code.NotFound) {
+          logger.warn("Parent agent not found", {
+            agentId,
+            error: error.rawMessage,
+          });
+          throw notFoundError("Agent", agentId);
+        }
+        throw internalError(error, "failed to load parent agent");
       }
 
       logger.debug("Loaded parent agent", {

package/src/domain/agentshare/controller.ts

@@ -13,10 +13,15 @@
  * cascade of same-org shares lives in the AGENT domain (ported with #6);
  * share delete itself cascades nothing.
  *
- * Authorization posture (OSS): single-user and local, so handlers perform
- * no authorization — a documented no-op, not a silent divergence. The
- * cloud edition enforces the same contracts via FGA plus app-level gates
- * for the anonymous resolution paths.
+ * Every chain opens with Authorize. create asks can_edit on the referenced
+ * agent, then can_create_agent_share (AuthorizeResolvedTarget); create and
+ * delete run the shared tuple-lifecycle steps against the composed
+ * lifecycle; getByReference authorizes the loaded share as `get` would;
+ * getByAgent and list narrow through the composed list read scope. The
+ * public share-link read skips the Authorizer through is_public, and the
+ * member read asks can_view on the organization before the share loads
+ * (AuthorizeMemberAudience). Per-RPC posture:
+ * docs/authorization-coverage.md §9.
  *
  * Proven by agentshare.conformance.test.ts (CONFORMANCE_TARGET=local),
  * __tests__/agentshare.test.ts and __tests__/store-faults.test.ts.
@@ -657,9 +662,9 @@ function newLoadSharesByAgentStep(
 const LIST_RESULT_KEY = "listResult";
 
 /**
- * List — org + labels filter (AND semantics), newest first. Versus Cloud,
- * OSS excludes authorization filtering AND pagination, exactly as Go's
- * list.go records.
+ * List — org + labels filter (AND semantics), newest first, narrowed to
+ * the caller's authorized rows by the composed list read scope.
+ * Unpaginated, exactly as Go's list.go records.
  */
 async function list(
   deps: AgentShareControllerDeps,

package/src/domain/artifact/file-server.ts

@@ -1,9 +1,12 @@
 /**
  * The artifact HTTP file server — ports the local-download lane from Go
  * pkg/server/server.go (artifactDownloadHandler + the boot block, lines
- * 849–926): a second listener on 127.0.0.1:ARTIFACT_HTTP_PORT (default
- * grpcPort+1), started only when artifact storage is LOCAL, serving
- * GET /<key> as the exact bytes LocalArtifactStorage wrote. The lane
+ * 849–926): a second listener on 127.0.0.1:ARTIFACT_HTTP_PORT (unset: the
+ * unified port + 1, ephemeral beside an ephemeral unified port — the rule is
+ * boot/artifact-lane.ts), started only when artifact storage is LOCAL,
+ * serving GET /<key> as the exact bytes LocalArtifactStorage wrote. Unlike
+ * Go, a bind failure fails the boot: the composition binds the lane before
+ * SERVING and lets listen()'s rejection stand (stigmer#1089). The lane
  * dissolved into its owning domain per the ratified D4 decision — it is
  * NOT a unified-port lane (Go runs it as a separate listener, and so does
  * this port).
@@ -39,7 +42,8 @@ export interface ArtifactFileServerOptions {
 
 export interface ArtifactFileServer {
   /**
-   * Binds <host>:<port> (an explicit port 0 picks ephemeral for tests).
+   * Binds <host>:<port> (port 0 picks ephemeral) and resolves the port it
+   * bound; a bind failure rejects, and the composition fails the boot on it.
    * The host is the composition root's call: 127.0.0.1 everywhere by
    * default (ARTIFACT_HTTP_HOST, DD-013) — download URLs are minted for
    * the local machine — and 0.0.0.0 only inside the official container

package/src/domain/channelapp/controller.ts

@@ -14,9 +14,14 @@
  * not_search_indexed — configuration reached through its parent surface,
  * not a library artifact), so no index steps appear in any chain.
  *
- * Versus Stigmer Cloud, OSS excludes the Authorize, CreateIamPolicies, and
- * Publish steps (single-user local posture); validation, secret handling,
- * and the referential delete block are byte-compatible.
+ * Every chain opens with Authorize; create and delete run the shared
+ * tuple-lifecycle steps against the composed lifecycle; getByReference
+ * loads, then authorizes the loaded app exactly as `get` would
+ * (AuthorizeResolvedTarget). listByOrg does not yet narrow through the
+ * list read scope, although the model restricts viewing to owners,
+ * explicit grants and organization admins
+ * (fga/model/agentic/channel_app.fga, stigmer/stigmer#1384). Per-RPC
+ * posture: docs/authorization-coverage.md §13.
  *
  * Proven by channelapp.conformance.test.ts (CONFORMANCE_TARGET=local)
  * and __tests__/channelapp.test.ts.

package/src/domain/environment/controller.ts

@@ -11,11 +11,14 @@
  * Proven by environment.conformance.test.ts (CONFORMANCE_TARGET=local),
  * __tests__/environment.test.ts and __tests__/store-faults.test.ts.
  *
- * Versus Stigmer Cloud, OSS excludes the Authorize, CreateIamPolicies,
- * FGA-tuple, and Publish steps (no multi-tenant auth, IAM/FGA, or event
- * publishing here); the visibility ceiling (org — secrets never resolve
- * across the org boundary) and share restrictions run in BOTH editions
- * from the same proto config, keeping the error contract identical.
+ * Every chain opens with Authorize; create, delete and updateVisibility run
+ * the shared tuple-lifecycle steps against the composed lifecycle;
+ * getByReference loads, then authorizes the loaded environment exactly as
+ * `get` would (AuthorizeResolvedTarget); list narrows through the composed
+ * list read scope. The visibility ceiling (org — secrets never resolve
+ * across the org boundary) and share restrictions come from the same proto
+ * config in every edition, keeping the error contract identical. Per-RPC
+ * posture: docs/authorization-coverage.md §3.
  */
 import type { ConnectRouter, HandlerContext } from "@connectrpc/connect";
 import { create, fromBinary } from "@bufbuild/protobuf";
@@ -734,9 +737,9 @@ async function getSecretValue(
 const LIST_RESULT_KEY = "listResult";
 
 /**
- * List — org + labels filter with per-item redaction. Versus Cloud, OSS
- * excludes authorization filtering AND pagination (returns all matches),
- * exactly as Go's list.go records.
+ * List — org + labels filter with per-item redaction, narrowed to the
+ * caller's authorized rows by the composed list read scope. Unpaginated
+ * (returns all matches), exactly as Go's list.go records.
  */
 async function list(
   deps: EnvironmentControllerDeps,

package/src/domain/executioncontext/controller.ts

@@ -25,10 +25,13 @@
  * (the decrypt-lane matrix conformance deliberately never exercises —
  * its harness authenticates as a user).
  *
- * Versus Stigmer Cloud, OSS excludes the Authorize, CreateIamPolicies,
- * and Publish steps (no multi-tenant auth, IAM/FGA, or event publishing
- * here); the redaction and decrypt-lane contracts run in BOTH editions,
- * keeping the error contract identical.
+ * Every chain opens with Authorize; create asks can_create_execution_in on
+ * the organization (AuthorizeCreate), and create and delete run the shared
+ * tuple-lifecycle steps against the composed lifecycle; getByReference
+ * loads, then authorizes the loaded context exactly as `get` would
+ * (AuthorizeResolvedTarget). The redaction and decrypt-lane contracts are
+ * the same in every edition, keeping the error contract identical. Per-RPC
+ * posture: docs/authorization-coverage.md §5.
  */
 import type { ConnectRouter, HandlerContext } from "@connectrpc/connect";