@stigmer/server 3.39.0 → 3.40.0

package/src/domain/memory/steps.ts

@@ -17,7 +17,7 @@
  * Proven by memory.conformance.test.ts (CONFORMANCE_TARGET=local) and
  * __tests__/memory.test.ts.
  */
-import { create, equals, fromBinary } from "@bufbuild/protobuf";
+import { create, equals, fromBinary, isMessage } from "@bufbuild/protobuf";
 import { timestampNow } from "@bufbuild/protobuf/wkt";
 import type { ConnectError } from "@connectrpc/connect";
 
@@ -30,6 +30,8 @@ import { MemoryListSchema } from "@stigmer/protos/ai/stigmer/agentic/memory/v1/i
 import { MemoryProvenanceSchema } from "@stigmer/protos/ai/stigmer/agentic/memory/v1/spec_pb";
 import { MemoryStatusSchema } from "@stigmer/protos/ai/stigmer/agentic/memory/v1/status_pb";
 import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import type { IdentityAccount } from "@stigmer/protos/ai/stigmer/iam/identityaccount/v1/api_pb";
+import { IdentityAccountSchema } from "@stigmer/protos/ai/stigmer/iam/identityaccount/v1/api_pb";
 import { IamPermission } from "@stigmer/protos/ai/stigmer/iam/v1/enum_pb";
 import { OrganizationSchema } from "@stigmer/protos/ai/stigmer/tenancy/organization/v1/api_pb";
 
@@ -52,10 +54,16 @@ import {
 import { memoryCaptureCredentialOf } from "../../pipeline/steps/guard-memory-capture.js";
 import { compareCreatedAtDesc } from "../../pipeline/steps/helpers.js";
 import { EXISTING_RESOURCE_KEY } from "../../pipeline/steps/load-existing.js";
+import type { AccountsByCaller } from "../identityaccount/resolve.js";
+import {
+  accountForCaller,
+  accountForStamp,
+} from "../identityaccount/resolve.js";
 import { ResourceNotFoundError } from "../../store/interface.js";
 import type { Store } from "../../store/interface.js";
 import {
   MAX_MEMORIES_PER_SUBJECT,
+  MEMORY_ACCOUNT_DISABLED_MESSAGE,
   MEMORY_FULL_MESSAGE,
   MEMORY_PROVENANCE_IMMUTABLE_MESSAGE,
   MEMORY_SUBJECT_IMMUTABLE_MESSAGE,
@@ -77,10 +85,22 @@ export const LIST_RESULT_KEY = "listResult";
  *     memories are id-addressed records (the remember tool sends content
  *     only), and the platform's slug machinery requires a name. A
  *     client-supplied name still wins — the default only fills absence.
- *  3. Overwrites spec.subject_identity_account_id with the empty-string
- *     sentinel — the OSS single-user subject (the OAuth grant store
- *     convention). Server-derived, never client-supplied (DD-005 D2):
- *     the cloud edition writes the caller's identity account here.
+ *  3. Overwrites spec.subject_identity_account_id, server-derived and
+ *     never client-supplied (DD-005 D2), by posture. Under the
+ *     single-operator posture (no `personAccounts` composed) it is the
+ *     empty-string sentinel — the laptop's one subject (the OAuth grant
+ *     store convention). Where callers are persons it is the id of the
+ *     identity account the memory is ABOUT (stigmer#1387, the Java
+ *     MemoryCreateHandler's subject): the admitted capture credential's
+ *     subject (point 5), else the calling person — each resolved through
+ *     the identity-account domain (accountForStamp / accountForCaller),
+ *     so a subject that arrived as a raw issuer subject is filed under
+ *     the account every FGA tuple names. The resolved account rides the
+ *     context under MEMORY_SUBJECT_ACCOUNT_KEY for CheckMemoryEnablement,
+ *     so the subject stamped and the consent checked are one row, read
+ *     once. A caller no account stands for is stamped "" and NOT refused
+ *     here: the refusal belongs behind AuthorizeResolvedTarget, which
+ *     runs between the two steps so a refused caller learns nothing.
  *  4. Stores spec.provenance as supplied (Stage 3 provenance decision,
  *     owner-ratified 2026-08-22): the capture path — the remember tool
  *     via the runner-synthesized attachment — threads the agent/session/
@@ -101,15 +121,15 @@ export const LIST_RESULT_KEY = "listResult";
  *     human ("the sub IS the human subject the session belongs to",
  *     Java MemoryCreateHandler) and provenance.session_id is overridden
  *     with the token's own session claim (server-proved beats
- *     runner-reported). Absent the handoff, the OSS arms above apply
+ *     runner-reported). Absent the handoff, the arms above apply
  *     unchanged.
  */
-export function newResolveMemoryDefaultsStep(): PipelineStep<
-  typeof MemorySchema
-> {
+export function newResolveMemoryDefaultsStep(
+  personAccounts?: AccountsByCaller,
+): PipelineStep<typeof MemorySchema> {
   return {
     name: "ResolveMemoryDefaults",
-    execute(ctx: RequestContext<typeof MemorySchema>): void {
+    async execute(ctx: RequestContext<typeof MemorySchema>): Promise<void> {
       const memory = ctx.newState;
       const metadata = memory.metadata;
 
@@ -138,11 +158,23 @@ export function newResolveMemoryDefaultsStep(): PipelineStep<
         );
       }
 
-      // The subject stays server-owned (DD-005 D2): the OSS sentinel, or
-      // the admitted capture credential's proved human (step doc point 5).
+      // The subject stays server-owned (DD-005 D2), by posture (step doc
+      // points 3 and 5).
       const captureCredential = memoryCaptureCredentialOf(ctx);
-      spec.subjectIdentityAccountId =
-        captureCredential?.subjectIdentityAccountId ?? "";
+      if (personAccounts === undefined) {
+        spec.subjectIdentityAccountId =
+          captureCredential?.subjectIdentityAccountId ?? "";
+      } else {
+        const account = await resolveSubjectAccount(
+          personAccounts,
+          ctx,
+          captureCredential?.subjectIdentityAccountId,
+        );
+        spec.subjectIdentityAccountId = account?.metadata?.id ?? "";
+        if (account !== undefined) {
+          ctx.set(MEMORY_SUBJECT_ACCOUNT_KEY, account);
+        }
+      }
 
       // Provenance is capture-path-supplied (see the step doc, point 4);
       // only tool_call_id is force-cleared — unreachable via MCP in v1, so
@@ -162,6 +194,54 @@ export function newResolveMemoryDefaultsStep(): PipelineStep<
   };
 }
 
+/**
+ * Context key carrying the identity account a memory is about, from
+ * ResolveMemoryDefaults to CheckMemoryEnablement — present exactly when
+ * callers are persons and the subject resolved (step doc point 3).
+ */
+export const MEMORY_SUBJECT_ACCOUNT_KEY = "memorySubjectAccount";
+
+/** The subject's account stashed by ResolveMemoryDefaults, if any. */
+export function memorySubjectAccountOf(
+  ctx: RequestContext<typeof MemorySchema>,
+): IdentityAccount | undefined {
+  const payload = ctx.get(MEMORY_SUBJECT_ACCOUNT_KEY);
+  return isMessage(payload, IdentityAccountSchema) ? payload : undefined;
+}
+
+/**
+ * The account the memory is about: the capture credential's subject read
+ * as a creator-style stamp (an account id, or a raw issuer subject), else
+ * the account the calling person stands for. `undefined` when nobody
+ * resolves. A store fault is an infrastructure fault; an account row with
+ * no id is a loud one, never an empty principal (the resolve.ts rule).
+ */
+async function resolveSubjectAccount(
+  personAccounts: AccountsByCaller,
+  ctx: RequestContext<typeof MemorySchema>,
+  credentialSubject: string | undefined,
+): Promise<IdentityAccount | undefined> {
+  let account: IdentityAccount | undefined;
+  try {
+    account =
+      credentialSubject !== undefined
+        ? await accountForStamp(personAccounts, credentialSubject)
+        : await accountForCaller(personAccounts, ctx.callerIdentity);
+  } catch (error) {
+    throw internalError(
+      error,
+      "failed to resolve the identity account a memory is about",
+    );
+  }
+  if (account !== undefined && (account.metadata?.id ?? "") === "") {
+    throw internalError(
+      new Error("identity account carries no id"),
+      "failed to resolve the identity account a memory is about",
+    );
+  }
+  return account;
+}
+
 /** The deny copy of the create lane's organization bar. */
 export const MEMORY_CREATE_DENIED_MESSAGE =
   "unauthorized to capture memory in this organization";
@@ -212,15 +292,22 @@ export function resolveMemoryCreateTargets(
  * authorization: "the label is not authorization; the server refuses"
  * (the conversation-attachment doctrine, applied verbatim).
  *
- * OSS checks the org flag alone — the user scope collapses in single-user
- * local mode (DD-006 D1). The cloud edition additionally requires the
- * caller's own memory_enabled and the strict first-party-human gate.
+ * The double opt-in (DD-006 D1), in the Java handler's order: the
+ * organization's switch first (the gate an admin controls), then — where
+ * callers are persons (`personAccounts` composed) — the switch of the
+ * person the memory is about, read from the account ResolveMemoryDefaults
+ * resolved and stashed (stigmer#1387). No stashed account under that
+ * posture refuses with the person's copy: nobody the server can name has
+ * consented. The single-operator posture checks the org flag alone — its
+ * one operator is the organization's decider. Who may capture at all is
+ * GuardMemoryCapture's question, not this step's.
  *
  * Reads the Organization row directly from the store, matching Go — no
  * cross-domain client.
  */
 export function newCheckMemoryEnablementStep(
   store: Store,
+  personAccounts?: AccountsByCaller,
 ): PipelineStep<typeof MemorySchema> {
   return {
     name: "CheckMemoryEnablement",
@@ -247,6 +334,14 @@ export function newCheckMemoryEnablementStep(
       if (org.spec?.preferences?.memoryEnabled !== true) {
         throw failedPreconditionError(memoryDisabledMessage(orgID));
       }
+
+      if (personAccounts === undefined) {
+        return;
+      }
+      const subject = memorySubjectAccountOf(ctx);
+      if (subject?.spec?.preferences?.memoryEnabled !== true) {
+        throw failedPreconditionError(MEMORY_ACCOUNT_DISABLED_MESSAGE);
+      }
     },
   };
 }

package/src/domain/organization/controller.ts

@@ -20,10 +20,13 @@
  * carries the other two edition forks: find's enumeration posture and
  * findMyOrganizations' filtering (see organization-directory.ts).
  *
- * Versus Stigmer Cloud's Java service, plain OSS excludes the
- * CreateIamPolicies and Publish steps; with the C2 seam composed, the
- * CreateAuthorizationTuples/CleanupIamPolicies steps deliver the same
- * lifecycle through the resourceAuthorizationLifecycle driver.
+ * Every chain opens with Authorize; create and delete run the shared
+ * tuple-lifecycle steps (CreateAuthorizationTuples, CleanupIamPolicies)
+ * against the lifecycle compose.ts hands it: a composed
+ * resourceAuthorizationLifecycle driver when a unit registers one, else,
+ * under the built-in posture, open source's role lifecycle (the creator's
+ * `owner` row), and under trusted-local none, where the steps no-op.
+ * Per-RPC posture: docs/authorization-coverage.md §2.
  */
 import type { ConnectRouter, HandlerContext } from "@connectrpc/connect";
 import { Code, ConnectError } from "@connectrpc/connect";

package/src/domain/plugin/__tests__/plugin.test.ts

@@ -104,6 +104,10 @@ beforeAll(async () => {
       STIGMER_MODEL_REGISTRY_REFRESH: "off",
       TEMPORAL_HOST_PORT: "127.0.0.1:1",
       GRPC_PORT: String(grpcPort),
+      // The reserved port is the unified one only; its +1 neighbour is not
+      // reserved, and a lane that cannot bind fails the boot (#1089), so
+      // the artifact lane binds ephemeral.
+      ARTIFACT_HTTP_PORT: "0",
       DB_PATH: path.join(dir, "stigmer.db"),
       ARTIFACT_LOCAL_BASE_PATH: path.join(dir, "artifacts"),
       STORAGE_PATH: path.join(dir, "storage"),
@@ -801,6 +805,10 @@ describe("Plugin push under an authorizer that enforces reserved labels", () =>
         STIGMER_MODEL_REGISTRY_REFRESH: "off",
         TEMPORAL_HOST_PORT: "127.0.0.1:1",
         GRPC_PORT: String(grpcPort),
+        // The reserved port is the unified one only; its +1 neighbour is not
+        // reserved, and a lane that cannot bind fails the boot (#1089), so
+        // the artifact lane binds ephemeral.
+        ARTIFACT_HTTP_PORT: "0",
         DB_PATH: path.join(enforcingDir, "stigmer.db"),
         ARTIFACT_LOCAL_BASE_PATH: path.join(enforcingDir, "artifacts"),
         STORAGE_PATH: path.join(enforcingDir, "storage"),

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

@@ -0,0 +1,104 @@
+/**
+ * Pins the store-fault contract of the plugin's visibility-update load: a
+ * typed ResourceNotFoundError answers NotFound with the domain's pinned copy
+ * (`plugin 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 plugin does not exist (stigmer/stigmer#1345).
+ *
+ * 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 archive store and the member materializer are untouchable: a load that
+ * fails must stop the call before the plugin's level fans out to its members.
+ *
+ * Out of scope: the NotFound copy itself (wire contract).
+ */
+import type { Client, ConnectError } from "@connectrpc/connect";
+import { Code, createClient, createRouterTransport } from "@connectrpc/connect";
+import { describe, expect, it } from "vitest";
+
+import { PluginCommandController } from "@stigmer/protos/ai/stigmer/agentic/plugin/v1/command_pb";
+import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
+
+import { createLogger } from "../../../boot/logger.js";
+import { createApiResourceInterceptor } from "../../../pipeline/interceptors/apiresource.js";
+import { createVerifierChainInterceptor } from "../../../pipeline/interceptors/auth.js";
+import {
+  errorOf,
+  failingStore,
+  untouchable,
+} from "../../../pipeline/__tests__/support.js";
+import { newPermissiveSingleTeamAuthorizer } from "../../../pipeline/steps/authorize.js";
+import { ResourceNotFoundError } from "../../../store/interface.js";
+import type { Store } from "../../../store/interface.js";
+
+import { registerPluginServices } from "../controller.js";
+
+const silentLogger = createLogger({
+  level: "error",
+  pretty: false,
+  write: () => {},
+});
+
+const PLUGIN_ID = "plg_storefault";
+
+const NOT_FOUND_COPY = `plugin not found: ${PLUGIN_ID}`;
+const LOAD_FAULT_COPY = "failed to load plugin";
+
+const MISSING = (): Error => new ResourceNotFoundError(`plugin/${PLUGIN_ID}`);
+const LOCKED = (): Error => new Error("SQLITE_BUSY: database is locked");
+
+/**
+ * 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.
+ */
+function pluginCommand(store: Store): Client<typeof PluginCommandController> {
+  const transport = createRouterTransport(
+    (router) => {
+      registerPluginServices(router, {
+        store,
+        logger: silentLogger,
+        authorizer: newPermissiveSingleTeamAuthorizer(),
+        authorizationLifecycle: undefined,
+        artifactStorage: untouchable("artifactStorage"),
+        materializerProvider: untouchable("materializerProvider"),
+      });
+    },
+    {
+      router: {
+        interceptors: [
+          createVerifierChainInterceptor([], [], silentLogger),
+          createApiResourceInterceptor(),
+        ],
+      },
+    },
+  );
+  return createClient(PluginCommandController, transport);
+}
+
+describe("updateVisibility — LoadPluginForVisibilityUpdate", () => {
+  function surfaceError(store: Store): Promise<ConnectError> {
+    return errorOf(() =>
+      pluginCommand(store).updateVisibility({
+        resourceId: PLUGIN_ID,
+        visibility: ApiResourceVisibility.visibility_private,
+      }),
+    );
+  }
+
+  it("a missing plugin answers NotFound with the domain's copy", async () => {
+    const error = await surfaceError(failingStore(MISSING()));
+
+    expect(error.code).toBe(Code.NotFound);
+    expect(error.rawMessage).toBe(NOT_FOUND_COPY);
+  });
+
+  it("any other store failure answers a sanitized Internal", async () => {
+    const error = await surfaceError(failingStore(LOCKED()));
+
+    expect(error.code).toBe(Code.Internal);
+    expect(error.rawMessage).toBe(LOAD_FAULT_COPY);
+  });
+});

package/src/domain/plugin/controller.ts

@@ -16,8 +16,9 @@
  * in-process clients it rides exist only after the routes this controller
  * is registered in.
  *
- * Proven by __tests__/plugin.test.ts (composed-server round-trips) and
- * plugin.conformance.test.ts (CONFORMANCE_TARGET=local, local-postgres).
+ * Proven by __tests__/plugin.test.ts (composed-server round-trips),
+ * __tests__/store-faults.test.ts and plugin.conformance.test.ts
+ * (CONFORMANCE_TARGET=local, local-postgres).
  */
 import { create, fromBinary } from "@bufbuild/protobuf";
 import type { ConnectRouter, HandlerContext } from "@connectrpc/connect";
@@ -104,6 +105,7 @@ import {
 } from "../../pipeline/steps/authorize-resolved-target.js";
 import type { VersionHistoryBinding } from "../../pipeline/steps/version-history.js";
 import { metadataOf } from "../../pipeline/steps/shapes.js";
+import { ResourceNotFoundError } from "../../store/interface.js";
 import type { Store } from "../../store/interface.js";
 import type {
   ArchiveStaging,
@@ -386,7 +388,7 @@ async function updateVisibility(
   return reqCtx.get(UPDATE_VISIBILITY_PLUGIN_KEY) as Plugin;
 }
 
-/** Loads the plugin by resource_id; ANY load failure → NotFound. */
+/** Loads the plugin by resource_id; a missing one answers NotFound, a store fault Internal. */
 function newLoadPluginByIdStep(
   store: Store,
   key: string,
@@ -401,8 +403,11 @@ function newLoadPluginByIdStep(
           ctx.input.resourceId,
           PluginSchema,
         );
-      } catch {
-        throw notFoundError("plugin", ctx.input.resourceId);
+      } catch (error) {
+        if (error instanceof ResourceNotFoundError) {
+          throw notFoundError("plugin", ctx.input.resourceId);
+        }
+        throw internalError(error, "failed to load plugin");
       }
       ctx.set(key, plugin);
     },

package/src/domain/session/controller.ts

@@ -13,9 +13,13 @@
  * Proven by session.conformance.test.ts (CONFORMANCE_TARGET=local) and
  * __tests__/session.test.ts.
  *
- * Versus Stigmer Cloud, OSS excludes the Authorize, CreateIamPolicies, and
- * Publish steps (no multi-tenant auth, IAM/FGA, or event publishing here)
- * and the FGA-authorized list filtering.
+ * Every chain opens with Authorize, and create also asks can_execute on
+ * the agent instance it binds to (AuthorizeRunTarget); create and delete
+ * run the shared tuple-lifecycle steps against the composed lifecycle;
+ * updateSubject evaluates its annotation through authorizeDirect after the
+ * load (#224); list, listByAgentInstance and listByChannel narrow through
+ * the composed list read scope. Per-RPC posture:
+ * docs/authorization-coverage.md §8.
  */
 import type { ConnectRouter, HandlerContext } from "@connectrpc/connect";
 

package/src/domain/skill/__tests__/skill.test.ts

@@ -74,6 +74,10 @@ beforeAll(async () => {
       // a live local Temporal (the conformance CRUD harness does the same).
       TEMPORAL_HOST_PORT: "127.0.0.1:1",
       GRPC_PORT: String(grpcPort),
+      // The reserved port is the unified one only; its +1 neighbour is not
+      // reserved, and a lane that cannot bind fails the boot (#1089), so
+      // the artifact lane binds ephemeral.
+      ARTIFACT_HTTP_PORT: "0",
       DB_PATH: path.join(dir, "stigmer.db"),
       ARTIFACT_LOCAL_BASE_PATH: path.join(dir, "artifacts"),
       STORAGE_PATH: path.join(dir, "storage"),

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

@@ -0,0 +1,103 @@
+/**
+ * Pins the store-fault contract of the skill's visibility-update load: a
+ * typed ResourceNotFoundError answers NotFound with the domain's pinned copy
+ * (`skill 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 skill does not exist (stigmer/stigmer#1345).
+ *
+ * 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 artifact storage is untouchable: a load that fails must stop the call
+ * before anything past it runs.
+ *
+ * Out of scope: the NotFound copy itself (wire contract).
+ */
+import type { Client, ConnectError } from "@connectrpc/connect";
+import { Code, createClient, createRouterTransport } from "@connectrpc/connect";
+import { describe, expect, it } from "vitest";
+
+import { SkillCommandController } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/command_pb";
+import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
+
+import { createLogger } from "../../../boot/logger.js";
+import { createApiResourceInterceptor } from "../../../pipeline/interceptors/apiresource.js";
+import { createVerifierChainInterceptor } from "../../../pipeline/interceptors/auth.js";
+import {
+  errorOf,
+  failingStore,
+  untouchable,
+} from "../../../pipeline/__tests__/support.js";
+import { newPermissiveSingleTeamAuthorizer } from "../../../pipeline/steps/authorize.js";
+import { ResourceNotFoundError } from "../../../store/interface.js";
+import type { Store } from "../../../store/interface.js";
+
+import { registerSkillServices } from "../controller.js";
+
+const silentLogger = createLogger({
+  level: "error",
+  pretty: false,
+  write: () => {},
+});
+
+const SKILL_ID = "skl_storefault";
+
+const NOT_FOUND_COPY = `skill not found: ${SKILL_ID}`;
+const LOAD_FAULT_COPY = "failed to load skill";
+
+const MISSING = (): Error => new ResourceNotFoundError(`skill/${SKILL_ID}`);
+const LOCKED = (): Error => new Error("SQLITE_BUSY: database is locked");
+
+/**
+ * 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.
+ */
+function skillCommand(store: Store): Client<typeof SkillCommandController> {
+  const transport = createRouterTransport(
+    (router) => {
+      registerSkillServices(router, {
+        store,
+        logger: silentLogger,
+        authorizer: newPermissiveSingleTeamAuthorizer(),
+        authorizationLifecycle: undefined,
+        artifactStorage: untouchable("artifactStorage"),
+      });
+    },
+    {
+      router: {
+        interceptors: [
+          createVerifierChainInterceptor([], [], silentLogger),
+          createApiResourceInterceptor(),
+        ],
+      },
+    },
+  );
+  return createClient(SkillCommandController, transport);
+}
+
+describe("updateVisibility — LoadSkillForVisibilityUpdate", () => {
+  function surfaceError(store: Store): Promise<ConnectError> {
+    return errorOf(() =>
+      skillCommand(store).updateVisibility({
+        resourceId: SKILL_ID,
+        visibility: ApiResourceVisibility.visibility_private,
+      }),
+    );
+  }
+
+  it("a missing skill answers NotFound with the domain's copy", async () => {
+    const error = await surfaceError(failingStore(MISSING()));
+
+    expect(error.code).toBe(Code.NotFound);
+    expect(error.rawMessage).toBe(NOT_FOUND_COPY);
+  });
+
+  it("any other store failure answers a sanitized Internal", async () => {
+    const error = await surfaceError(failingStore(LOCKED()));
+
+    expect(error.code).toBe(Code.Internal);
+    expect(error.rawMessage).toBe(LOAD_FAULT_COPY);
+  });
+});

package/src/domain/skill/controller.ts

@@ -13,8 +13,14 @@
  * optional deps; every absent-surface answer is a deliberate arm, not an
  * accident.
  *
- * Versus Stigmer Cloud, OSS excludes the TransformResponse/SendResponse
- * steps (no response transformation). The transfer lane's capability
+ * Every chain opens with Authorize; push runs the tuple-lifecycle splice
+ * (SkillPushAuthorizationTuples), and updateVisibility and delete the
+ * shared tuple steps; getByReference and listVersions authorize the
+ * resolved skill as `get` would; getArtifact and getArtifactDownloadUrl
+ * skip authorization by design, the content-hash key being the capability
+ * (docs/authorization-coverage.md §21).
+ *
+ * The transfer lane's capability
  * URLs come from the blob driver through the staging port
  * (transfer/staging.ts): the local driver's point at this server's own
  * HTTP lane, a bucket driver's straight at the bucket — same
@@ -99,6 +105,7 @@ import { newGuardReservedLabelsStep } from "../../pipeline/steps/guard-reserved-
 import { newValidateProtoStep } from "../../pipeline/steps/validation.js";
 import { newValidateVisibilityUpdateStep } from "../../pipeline/steps/validate-visibility.js";
 import { newDeleteVersionArchivesStep } from "../../pipeline/steps/version-archive.js";
+import { ResourceNotFoundError } from "../../store/interface.js";
 import type { Store } from "../../store/interface.js";
 import { MAX_ZIP_SIZE, TRANSFER_LANE_NOT_CONFIGURED } from "./constants.js";
 import {
@@ -463,7 +470,7 @@ async function updateVisibility(
   return reqCtx.get(UPDATE_VISIBILITY_SKILL_KEY) as Skill;
 }
 
-/** Loads the skill by resource_id; ANY load failure → NotFound. */
+/** Loads the skill by resource_id; a missing one answers NotFound, a store fault Internal. */
 function newLoadSkillForVisibilityUpdateStep(
   store: Store,
 ): PipelineStep<UpdateVisibilityDesc> {
@@ -478,8 +485,11 @@ function newLoadSkillForVisibilityUpdateStep(
           input.resourceId,
           SkillSchema,
         );
-      } catch {
-        throw notFoundError("skill", input.resourceId);
+      } catch (error) {
+        if (error instanceof ResourceNotFoundError) {
+          throw notFoundError("skill", input.resourceId);
+        }
+        throw internalError(error, "failed to load skill");
       }
       ctx.set(UPDATE_VISIBILITY_SKILL_KEY, skill);
     },