@stigmer/server 3.15.3-dev.20260914121148 → 3.16.0

package/src/pipeline/errors.ts

@@ -24,7 +24,10 @@ export function invalidArgumentError(message: string): ConnectError {
 
 /** Go AlreadyExistsError: "%s already exists: %s". */
 export function alreadyExistsError(resource: string, id: string): ConnectError {
-  return new ConnectError(`${resource} already exists: ${id}`, Code.AlreadyExists);
+  return new ConnectError(
+    `${resource} already exists: ${id}`,
+    Code.AlreadyExists,
+  );
 }
 
 /**
@@ -109,10 +112,7 @@ export function goWrappedStatusError(
   prefix: string,
   error: ConnectError,
 ): ConnectError {
-  return new ConnectError(
-    `${prefix}: ${goGrpcErrorText(error)}`,
-    error.code,
-  );
+  return new ConnectError(`${prefix}: ${goGrpcErrorText(error)}`, error.code);
 }
 
 /**

package/src/pipeline/steps/__tests__/authorize-annotation-completeness.test.ts

@@ -55,7 +55,6 @@ import path from "node:path";
 
 import { getOption, hasOption } from "@bufbuild/protobuf";
 import type { DescService } from "@bufbuild/protobuf";
-import type { ConnectRouter } from "@connectrpc/connect";
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
 
 import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
@@ -71,6 +70,7 @@ import { loadConfig } from "../../../boot/config.js";
 import { composeServer } from "../../../boot/compose.js";
 import type { ComposedServer } from "../../../boot/compose.js";
 import { createLogger } from "../../../boot/logger.js";
+import { servedServices } from "../../../extensions/__tests__/composed-support.js";
 
 /** One annotated method as the invariant reads it. */
 interface AnnotationTarget {
@@ -80,25 +80,6 @@ interface AnnotationTarget {
   readonly skipsResolution: boolean;
 }
 
-/** Replays the composed routes into a recorder and returns the served services. */
-function servedServices(
-  routes: (router: ConnectRouter) => void,
-): DescService[] {
-  const served: DescService[] = [];
-  const recorder = {
-    handlers: [],
-    service(desc: DescService) {
-      served.push(desc);
-      return recorder;
-    },
-    rpc() {
-      return recorder;
-    },
-  };
-  routes(recorder as unknown as ConnectRouter);
-  return served;
-}
-
 /** Every `rpc.config`-annotated method of the given services, read once. */
 function annotationTargets(services: DescService[]): AnnotationTarget[] {
   const targets: AnnotationTarget[] = [];

package/src/pipeline/steps/__tests__/guard-memory-capture.test.ts

@@ -60,7 +60,10 @@ function memoryCtx(
 
 /** A provider whose only relevant surface is the capture capability. */
 function providerWith(
-  decide?: (caller: CallerIdentity, org: string) => MemoryCaptureDecision,
+  decide?: (
+    caller: CallerIdentity,
+    org: string,
+  ) => MemoryCaptureDecision | Promise<MemoryCaptureDecision>,
 ): RunnerCredentialProvider {
   return {
     isEnabled: () => false,
@@ -79,8 +82,34 @@ function jwtWith(payload: Record<string, unknown>): string {
   return `header.${body}.signature`;
 }
 
+async function rejectionOf(run: void | Promise<void>): Promise<unknown> {
+  return Promise.resolve(run).then(
+    () => {
+      throw new Error("expected the step to refuse");
+    },
+    (error: unknown) => error,
+  );
+}
+
 describe("GuardMemoryCapture with the capability composed", () => {
-  it("admit stashes the proved claims for ResolveMemoryDefaults", () => {
+  it("a capability that answers with a promise is awaited — the built-in provider reads the run's row for the session", async () => {
+    const step = newGuardMemoryCaptureStep<typeof MemorySchema>(
+      providerWith(() =>
+        Promise.resolve({
+          verdict: "admit" as const,
+          subjectIdentityAccountId: "ida_human",
+          provedSessionId: "ses_from_row",
+        }),
+      ),
+    );
+    const ctx = memoryCtx(SANDBOX_CALLER);
+    await step.execute(ctx);
+    expect(memoryCaptureCredentialOf(ctx)?.provedSessionId).toBe(
+      "ses_from_row",
+    );
+  });
+
+  it("admit stashes the proved claims for ResolveMemoryDefaults", async () => {
     const step = newGuardMemoryCaptureStep<typeof MemorySchema>(
       providerWith(() => ({
         verdict: "admit",
@@ -89,23 +118,18 @@ describe("GuardMemoryCapture with the capability composed", () => {
       })),
     );
     const ctx = memoryCtx(SANDBOX_CALLER);
-    step.execute(ctx);
+    await step.execute(ctx);
     expect(memoryCaptureCredentialOf(ctx)).toEqual({
       subjectIdentityAccountId: "ida_human",
       provedSessionId: "ses_proved",
     });
   });
 
-  it("refuse answers the byte-pinned PERMISSION_DENIED copy", () => {
+  it("refuse answers the byte-pinned PERMISSION_DENIED copy", async () => {
     const step = newGuardMemoryCaptureStep<typeof MemorySchema>(
       providerWith(() => ({ verdict: "refuse" })),
     );
-    let error: unknown;
-    try {
-      step.execute(memoryCtx(SANDBOX_CALLER));
-    } catch (e) {
-      error = e;
-    }
+    const error = await rejectionOf(step.execute(memoryCtx(SANDBOX_CALLER)));
     expect(error).toBeInstanceOf(ConnectError);
     expect((error as ConnectError).code).toBe(Code.PermissionDenied);
     expect((error as ConnectError).rawMessage).toBe(
@@ -113,7 +137,7 @@ describe("GuardMemoryCapture with the capability composed", () => {
     );
   });
 
-  it("hands the capability the caller and the capture org", () => {
+  it("hands the capability the caller and the capture org", async () => {
     const observed: Array<{ caller: CallerIdentity; org: string }> = [];
     const step = newGuardMemoryCaptureStep<typeof MemorySchema>(
       providerWith((caller, org) => {
@@ -121,11 +145,11 @@ describe("GuardMemoryCapture with the capability composed", () => {
         return { verdict: "no-opinion" };
       }),
     );
-    step.execute(memoryCtx(SANDBOX_CALLER, "org_zeta"));
+    await step.execute(memoryCtx(SANDBOX_CALLER, "org_zeta"));
     expect(observed).toEqual([{ caller: SANDBOX_CALLER, org: "org_zeta" }]);
   });
 
-  it("an org-mismatch throw from the capability propagates untouched", () => {
+  it("an org-mismatch throw from the capability propagates untouched", async () => {
     const mismatch = new ConnectError(
       "memory capture is scoped to the session's organization",
       Code.PermissionDenied,
@@ -135,16 +159,12 @@ describe("GuardMemoryCapture with the capability composed", () => {
         throw mismatch;
       }),
     );
-    let error: unknown;
-    try {
-      step.execute(memoryCtx(SANDBOX_CALLER, "org_other"));
-    } catch (e) {
-      error = e;
-    }
-    expect(error).toBe(mismatch);
+    expect(
+      await rejectionOf(step.execute(memoryCtx(SANDBOX_CALLER, "org_other"))),
+    ).toBe(mismatch);
   });
 
-  it("no-opinion falls through: platform_client_id carriers still refuse", () => {
+  it("no-opinion falls through: platform_client_id carriers still refuse", async () => {
     const step = newGuardMemoryCaptureStep<typeof MemorySchema>(
       providerWith(() => ({ verdict: "no-opinion" })),
     );
@@ -154,18 +174,18 @@ describe("GuardMemoryCapture with the capability composed", () => {
       issuer: "stigmer",
       rawToken: jwtWith({ platform_client_id: "pc_1" }),
     };
-    expect(() => step.execute(memoryCtx(minted))).toThrowError(
+    await expect(step.execute(memoryCtx(minted))).rejects.toThrowError(
       MEMORY_CAPTURE_CALLER_MESSAGE,
     );
   });
 
-  it("internal and in-process callers never consult the capability", () => {
+  it("internal and in-process callers never consult the capability", async () => {
     const step = newGuardMemoryCaptureStep<typeof MemorySchema>(
       providerWith(() => {
         throw new Error("must not be consulted");
       }),
     );
-    step.execute(
+    await step.execute(
       memoryCtx({
         identityId: "internal",
         callerClass: "internal",
@@ -173,17 +193,15 @@ describe("GuardMemoryCapture with the capability composed", () => {
         rawToken: "",
       }),
     );
-    step.execute(memoryCtx({ ...LOCAL_USER, origin: "in-process" }));
+    await step.execute(memoryCtx({ ...LOCAL_USER, origin: "in-process" }));
   });
 });
 
 describe("GuardMemoryCapture without the capability (the pre-seam gate)", () => {
-  it("admits trusted-local and OIDC callers", () => {
-    const step = newGuardMemoryCaptureStep<typeof MemorySchema>(
-      providerWith(),
-    );
-    step.execute(memoryCtx(LOCAL_USER));
-    step.execute(
+  it("admits trusted-local and OIDC callers", async () => {
+    const step = newGuardMemoryCaptureStep<typeof MemorySchema>(providerWith());
+    await step.execute(memoryCtx(LOCAL_USER));
+    await step.execute(
       memoryCtx({
         identityId: "ida_oidc",
         callerClass: "user",
@@ -193,30 +211,26 @@ describe("GuardMemoryCapture without the capability (the pre-seam gate)", () =>
     );
   });
 
-  it("refuses machine callers and platform_client_id carriers", () => {
-    const step = newGuardMemoryCaptureStep<typeof MemorySchema>(
-      providerWith(),
-    );
-    expect(() =>
+  it("refuses machine callers and platform_client_id carriers", async () => {
+    const step = newGuardMemoryCaptureStep<typeof MemorySchema>(providerWith());
+    await expect(
       step.execute(memoryCtx({ ...LOCAL_USER, callerClass: "machine" })),
-    ).toThrowError(MEMORY_CAPTURE_CALLER_MESSAGE);
-    expect(() =>
+    ).rejects.toThrowError(MEMORY_CAPTURE_CALLER_MESSAGE);
+    await expect(
       step.execute(
         memoryCtx({
           ...LOCAL_USER,
           rawToken: jwtWith({ platform_client_id: "pc_1" }),
         }),
       ),
-    ).toThrowError(MEMORY_CAPTURE_CALLER_MESSAGE);
+    ).rejects.toThrowError(MEMORY_CAPTURE_CALLER_MESSAGE);
   });
 
-  it("admits a runner-shaped caller — the recorded pre-fix posture", () => {
+  it("admits a runner-shaped caller — the recorded pre-fix posture", async () => {
     // With no capability composed the gate cannot classify runner
     // credentials — the single-user OSS posture admits them (the #564
     // narrowing is CLOUD policy, shipped in the cloud capability).
-    const step = newGuardMemoryCaptureStep<typeof MemorySchema>(
-      providerWith(),
-    );
-    step.execute(memoryCtx(SANDBOX_CALLER));
+    const step = newGuardMemoryCaptureStep<typeof MemorySchema>(providerWith());
+    await step.execute(memoryCtx(SANDBOX_CALLER));
   });
 });

package/src/pipeline/steps/__tests__/guard-plugin-managed.test.ts

@@ -0,0 +1,151 @@
+/**
+ * Pins the plugin-managed write guard's two-fact decision: a stored
+ * resource labelled with an EXISTING plugin's id refuses a client write
+ * with FAILED_PRECONDITION naming the plugin; a label whose plugin is gone
+ * locks nothing; an unlabelled resource passes; in-process and internal
+ * callers pass by structure; the request's own labels are never consulted;
+ * and the step reads the context key the chain names.
+ */
+import { describe, expect, it } from "vitest";
+import { Code, ConnectError } from "@connectrpc/connect";
+import { create } from "@bufbuild/protobuf";
+
+import { AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import { PluginSchema } from "@stigmer/protos/ai/stigmer/agentic/plugin/v1/api_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import type { CallerIdentity } from "../../../extensions/identity.js";
+import { PLUGIN_LABEL } from "../../apiresource-labels.js";
+import { RequestContext } from "../../request-context.js";
+import { ResourceNotFoundError } from "../../../store/interface.js";
+import type { Store } from "../../../store/interface.js";
+import { newGuardPluginManagedStep } from "../guard-plugin-managed.js";
+import { EXISTING_RESOURCE_KEY } from "../load-existing.js";
+
+const USER: CallerIdentity = {
+  identityId: "ida_alice",
+  callerClass: "user",
+  issuer: "stigmer",
+  rawToken: "tok",
+};
+const IN_PROCESS: CallerIdentity = { ...USER, origin: "in-process" };
+const INTERNAL: CallerIdentity = { ...USER, callerClass: "internal" };
+
+/** A store that knows one plugin row; everything else is not found. */
+function storeWith(pluginId: string | undefined): Store {
+  return {
+    getResource: (kind: ApiResourceKind, id: string) => {
+      if (kind === ApiResourceKind.plugin && id === pluginId) {
+        return Promise.resolve(
+          create(PluginSchema, { metadata: { id, slug: "thermos" } }),
+        );
+      }
+      return Promise.reject(
+        new ResourceNotFoundError(`${ApiResourceKind[kind]}/${id}`),
+      );
+    },
+  } as unknown as Store;
+}
+
+function ctxWithStored(
+  labels: Record<string, string>,
+  caller: CallerIdentity,
+  key = EXISTING_RESOURCE_KEY,
+) {
+  const ctx = new RequestContext(
+    AgentSchema,
+    // The REQUEST carries no plugin label: the guard must not read it.
+    create(AgentSchema, { metadata: { name: "reviewer", labels: {} } }),
+    caller,
+    ApiResourceKind.agent,
+  );
+  ctx.set(
+    key,
+    create(AgentSchema, {
+      metadata: { name: "reviewer", slug: "reviewer", labels },
+    }),
+  );
+  return ctx;
+}
+
+async function outcome(
+  promise: Promise<void> | void,
+): Promise<ConnectError | undefined> {
+  try {
+    await promise;
+    return undefined;
+  } catch (error) {
+    return error as ConnectError;
+  }
+}
+
+describe("GuardPluginManaged", () => {
+  it("refuses a client write to a member whose plugin exists, naming the plugin", async () => {
+    const step = newGuardPluginManagedStep<typeof AgentSchema>(
+      storeWith("plg_1"),
+    );
+    const error = await outcome(
+      step.execute(ctxWithStored({ [PLUGIN_LABEL]: "plg_1" }, USER)),
+    );
+    expect(error).toBeInstanceOf(ConnectError);
+    expect(error?.code).toBe(Code.FailedPrecondition);
+    expect(error?.rawMessage).toBe(
+      "agent 'reviewer' is managed by plugin 'thermos'; change the plugin and push it again, or compose your own agent over it",
+    );
+  });
+
+  it("locks nothing when the labelled plugin is gone", async () => {
+    const step = newGuardPluginManagedStep<typeof AgentSchema>(
+      storeWith(undefined),
+    );
+    expect(
+      await outcome(
+        step.execute(ctxWithStored({ [PLUGIN_LABEL]: "plg_gone" }, USER)),
+      ),
+    ).toBeUndefined();
+  });
+
+  it("passes an unlabelled resource without touching the store", async () => {
+    const step = newGuardPluginManagedStep<typeof AgentSchema>({
+      getResource: () => Promise.reject(new Error("must not be called")),
+    } as unknown as Store);
+    expect(
+      await outcome(step.execute(ctxWithStored({ team: "x" }, USER))),
+    ).toBeUndefined();
+  });
+
+  it("passes in-process and internal callers by structure", async () => {
+    const step = newGuardPluginManagedStep<typeof AgentSchema>(
+      storeWith("plg_1"),
+    );
+    expect(
+      await outcome(
+        step.execute(ctxWithStored({ [PLUGIN_LABEL]: "plg_1" }, IN_PROCESS)),
+      ),
+    ).toBeUndefined();
+    expect(
+      await outcome(
+        step.execute(ctxWithStored({ [PLUGIN_LABEL]: "plg_1" }, INTERNAL)),
+      ),
+    ).toBeUndefined();
+  });
+
+  it("reads the stored resource from the key the chain names", async () => {
+    const step = newGuardPluginManagedStep<typeof AgentSchema>(
+      storeWith("plg_1"),
+      { existingKey: "customKey" },
+    );
+    const error = await outcome(
+      step.execute(
+        ctxWithStored({ [PLUGIN_LABEL]: "plg_1" }, USER, "customKey"),
+      ),
+    );
+    expect(error?.code).toBe(Code.FailedPrecondition);
+    // Under the default key nothing is loaded, so nothing is refused.
+    expect(
+      await outcome(
+        step.execute(ctxWithStored({ [PLUGIN_LABEL]: "plg_1" }, USER)),
+      ),
+    ).toBeUndefined();
+  });
+});

package/src/pipeline/steps/__tests__/guard-reserved-labels.test.ts

@@ -11,7 +11,9 @@ import { describe, expect, it } from "vitest";
 import { Code, ConnectError } from "@connectrpc/connect";
 import { create } from "@bufbuild/protobuf";
 
+import type { Message } from "@bufbuild/protobuf";
 import { AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import { PushSkillRequestSchema } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/io_pb";
 import { EnvironmentSchema } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/api_pb";
 import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
 import { IamPermission } from "@stigmer/protos/ai/stigmer/iam/v1/enum_pb";
@@ -74,6 +76,75 @@ describe("reservedLabelMutations", () => {
   });
 });
 
+describe("GuardReservedLabels on a push-shaped chain (named positions)", () => {
+  // Skill push builds its resource from an artifact and rides SKILL_KEY /
+  // EXISTING_SKILL_KEY rather than newState / EXISTING_RESOURCE_KEY; the
+  // positions parameter points the guard at them. Pins that a reserved
+  // introduction on the BUILT resource is judged (the request itself has
+  // no metadata), that a stored echo under the named existing key passes,
+  // and that the in-process origin passes by structure.
+  const BUILT_KEY = "builtResource";
+  const STORED_KEY = "storedResource";
+  function pushCtx(
+    labels: Record<string, string>,
+    stored?: Record<string, string>,
+    caller: CallerIdentity = USER,
+  ) {
+    const ctx = new RequestContext(
+      PushSkillRequestSchema,
+      create(PushSkillRequestSchema, {
+        org: "acme",
+        artifact: new Uint8Array(1),
+        labels,
+      }),
+      caller,
+      ApiResourceKind.skill,
+    );
+    ctx.set(
+      BUILT_KEY,
+      create(AgentSchema, { metadata: { name: "s", labels } }),
+    );
+    if (stored !== undefined) {
+      ctx.set(
+        STORED_KEY,
+        create(AgentSchema, { metadata: { name: "s", labels: stored } }),
+      );
+    }
+    return ctx;
+  }
+  const positioned = (authorizer: Authorizer) =>
+    newGuardReservedLabelsStep<typeof PushSkillRequestSchema>(authorizer, {
+      stateOf: (ctx) => ctx.get(BUILT_KEY) as Message,
+      existingKey: STORED_KEY,
+    });
+
+  it("rejects a reserved introduction read from the named state", async () => {
+    const error = await positioned(denying())
+      .execute(pushCtx({ "stigmer.ai/plugin": "plg_1" }))
+      ?.catch((e: unknown) => e);
+    expect(error).toBeInstanceOf(ConnectError);
+    expect((error as ConnectError).code).toBe(Code.InvalidArgument);
+  });
+
+  it("passes an echo of the label stored under the named existing key", async () => {
+    await positioned(denying()).execute(
+      pushCtx(
+        { "stigmer.ai/plugin": "plg_1" },
+        { "stigmer.ai/plugin": "plg_1" },
+      ),
+    );
+  });
+
+  it("passes the in-process origin by structure", async () => {
+    await positioned(denying()).execute(
+      pushCtx({ "stigmer.ai/plugin": "plg_1" }, undefined, {
+        ...USER,
+        origin: "in-process",
+      }),
+    );
+  });
+});
+
 describe("GuardReservedLabels", () => {
   it("rejects an introduction with the byte-pinned copy when denied", async () => {
     const step = newGuardReservedLabelsStep<typeof AgentSchema>(denying());
@@ -133,9 +204,8 @@ describe("GuardReservedLabels", () => {
   });
 
   it("the Environment personal-label client contract passes", async () => {
-    const step = newGuardReservedLabelsStep<typeof EnvironmentSchema>(
-      denying(),
-    );
+    const step =
+      newGuardReservedLabelsStep<typeof EnvironmentSchema>(denying());
     const ctx = new RequestContext(
       EnvironmentSchema,
       create(EnvironmentSchema, {
@@ -151,7 +221,12 @@ describe("GuardReservedLabels", () => {
     const step = newGuardReservedLabelsStep<typeof AgentSchema>(denying());
     const ctx = agentCtx(
       { "stigmer.ai/default-instance": "true" },
-      { identityId: "internal", callerClass: "internal", issuer: "", rawToken: "" },
+      {
+        identityId: "internal",
+        callerClass: "internal",
+        issuer: "",
+        rawToken: "",
+      },
     );
     await expect(Promise.resolve(step.execute(ctx))).resolves.toBeUndefined();
   });
@@ -166,7 +241,9 @@ describe("GuardReservedLabels", () => {
       vouched,
       "stigmer.ai/workflow-execution-id",
     );
-    await expect(Promise.resolve(step.execute(vouched))).resolves.toBeUndefined();
+    await expect(
+      Promise.resolve(step.execute(vouched)),
+    ).resolves.toBeUndefined();
 
     const smuggled = agentCtx({
       "stigmer.ai/workflow-execution-id": "wfe_1",
@@ -176,9 +253,7 @@ describe("GuardReservedLabels", () => {
       smuggled,
       "stigmer.ai/workflow-execution-id",
     );
-    const error = await step
-      .execute(smuggled)
-      ?.catch((e: unknown) => e);
+    const error = await step.execute(smuggled)?.catch((e: unknown) => e);
     expect(error).toBeInstanceOf(ConnectError);
     expect((error as ConnectError).rawMessage).toContain(
       "stigmer.ai/default-agent",

package/src/pipeline/steps/authorization-facts.ts

@@ -0,0 +1,131 @@
+/**
+ * The facts a stored row's authorization tuples derive from, read back
+ * from the row (`RowAuthorizationFacts`, extensions/resource-authorization.ts)
+ * — the read-time twin of the tuple lifecycle's create-time resolution in
+ * authorization-tuples.ts, and deliberately not that function: the
+ * create-time one throws when a row is missing its organization or its
+ * parent (a create must not half-succeed), while a row read back years
+ * later is a fact, missing pieces included — an empty organization
+ * resolves `admin from organization` to nobody, it does not fault a read.
+ * The two cannot drift unnoticed: src/authorization/__tests__/facts.test.ts
+ * pins that a well-formed row resolves to the same links through both.
+ *
+ * Two readers share this one resolver, which is the reason it is a leaf
+ * of its own: the list lanes' shared helper (extensions/list-read-scope.ts)
+ * builds every candidate's `ListEntryMeta` through it, and the built-in
+ * authorizer (src/authorization/facts.ts) derives a loaded row's tuples
+ * through it. It imports the two pure leaves it needs (apiresource-meta,
+ * shapes) and the protos, and nothing else, so the seam may import it by
+ * value without a cycle — the third such leaf, beside those two.
+ *
+ * Every read is structural (shapes.ts's own premise: protobuf-es messages
+ * are plain objects sharing the generated metadata and audit types), so
+ * the resolver needs no schema — a list lane holds decoded rows of a kind
+ * it names, not their descriptors.
+ */
+import { AuthorizationScopeType } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/authorization_config_pb";
+import type { ParentRelationConfig } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/authorization_config_pb";
+import type { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
+import type { ApiResourceAudit } from "@stigmer/protos/ai/stigmer/commons/apiresource/status_pb";
+
+import type {
+  ResolvedParentLink,
+  RowAuthorizationFacts,
+} from "../../extensions/resource-authorization.js";
+import { getKindEnum, getKindMeta } from "../apiresource-meta.js";
+import { parentIdOf } from "./shapes.js";
+import type { HasMetadataShape } from "./shapes.js";
+
+/** The one path every stored API resource keeps its audit under. */
+interface HasAuditShape {
+  status?: { audit?: ApiResourceAudit };
+}
+
+/** The row's facts, read structurally; every absence is the empty value, never a throw. */
+export function rowAuthorizationFactsOf(
+  kind: ApiResourceKind,
+  resource: object,
+): RowAuthorizationFacts {
+  const metadata = (resource as HasMetadataShape).metadata;
+  const org = metadata?.org ?? "";
+  return {
+    id: metadata?.id ?? "",
+    org,
+    visibility:
+      metadata?.visibility ??
+      ApiResourceVisibility.api_resource_visibility_unspecified,
+    createdBy: createdByOf(resource),
+    parentLinks: parentLinksOf(kind, resource, org),
+  };
+}
+
+/** `status.audit.spec_audit.created_by.id` as stamped — "" when any link is absent. */
+export function createdByOf(resource: object): string {
+  return (
+    (resource as HasAuditShape).status?.audit?.specAudit?.createdBy?.id ?? ""
+  );
+}
+
+/**
+ * The scope link and every configured additional parent the row names, in
+ * the tuple lifecycle's order. A parent the row does not name is left out.
+ */
+export function parentLinksOf(
+  kind: ApiResourceKind,
+  resource: object,
+  org: string,
+): ReadonlyArray<ResolvedParentLink> {
+  const config = getKindMeta(kind).authorization;
+  if (config === undefined) {
+    return [];
+  }
+  const links: ResolvedParentLink[] = [];
+  switch (config.scopeType) {
+    case AuthorizationScopeType.ORGANIZATION:
+      if (org !== "") {
+        links.push({
+          relation: "organization",
+          parentKind: getKindEnum("organization"),
+          parentId: org,
+        });
+      }
+      break;
+    case AuthorizationScopeType.PARENT:
+      if (config.parent !== undefined) {
+        pushLink(links, resource, config.parent);
+      }
+      break;
+    case AuthorizationScopeType.OWNER_ONLY:
+    case AuthorizationScopeType.PLATFORM:
+    case AuthorizationScopeType.NONE:
+    case AuthorizationScopeType.UNSPECIFIED:
+      // No scope link: OWNER_ONLY by design; PLATFORM is dead config in
+      // both editions (the lifecycle warns and writes none); NONE and
+      // UNSPECIFIED are kinds outside the model.
+      break;
+    default: {
+      const exhaustive: never = config.scopeType;
+      throw new Error(`unknown scope type: ${String(exhaustive)}`);
+    }
+  }
+  for (const parent of config.additionalParents) {
+    pushLink(links, resource, parent);
+  }
+  return links;
+}
+
+function pushLink(
+  links: ResolvedParentLink[],
+  resource: object,
+  parent: ParentRelationConfig,
+): void {
+  const parentId = parentIdOf(resource, parent.specField);
+  if (parentId !== "") {
+    links.push({
+      relation: parent.relation,
+      parentKind: getKindEnum(parent.kind),
+      parentId,
+    });
+  }
+}