@stigmer/server 3.15.3-dev.20260914121148 → 3.16.0

package/src/extensions/list-read-scope.ts

@@ -32,7 +32,13 @@
  *
  *   - No scope composed = the OSS full scan, byte-identical (the four
  *     local conformance rosters pin it; the org argument is then not
- *     consulted either).
+ *     consulted either). That is the trusted-local posture. Under the
+ *     built-in authorization posture (src/authorization/posture.ts — an
+ *     authentication posture with no unit Authorizer) open source
+ *     composes its own scope (src/authorization/list-read-scope.ts): the
+ *     cloud's model, evaluated per candidate over the facts the candidate
+ *     carries, so a self-host's lists show a person what a `get` would
+ *     let them read. A unit's registered scope wins in every posture.
  *   - A scope only NARROWS. It never reorders, never adds; sort/filter
  *     tails, per-lane org intersection, and empty-set semantics (empty
  *     list, proto default instance, kind-skipped) stay consumer-owned
@@ -90,40 +96,55 @@
  *     the child's check and shown by the parent's — the row's truth, read
  *     from the field the tuple was derived from, and no widening: nobody
  *     reaches a parent through it who could not create the row in it.
+ *   - EVERY CANDIDATE CARRIES THE ROW'S AUTHORIZATION FACTS (the
+ *     built-in scope's entry): the creator stamp, the visibility level
+ *     and every parent link the tuple lifecycle would have written — the
+ *     `RowAuthorizationFacts` the row's tuples derive from, read by the
+ *     one structural resolver the built-in authorizer reads a loaded row
+ *     through (pipeline/steps/authorization-facts.ts). A driver that
+ *     evaluates the model over a candidate therefore needs no second
+ *     read of a row the lane already decoded; a driver that asks an
+ *     engine ignores the facts and is byte-neutral. The facts are
+ *     REQUIRED on the candidate, never optional: both are always on the
+ *     row the helper holds, and an optional field would let a driver
+ *     silently skip the check.
  */
 import type { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import type { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
+import type { ApiResourceAudit } from "@stigmer/protos/ai/stigmer/commons/apiresource/status_pb";
 
-// The first VALUE imports from extensions/ into pipeline/ (every other
-// crossing is a type): two pure leaf modules that import nothing but
-// protos, so there is no cycle. Deliberate — one resolver for the tuple
-// writer and the list reader beats a copy in the seam.
-import {
-  getKindEnum,
-  inheritedAuthorizationParentOf,
-} from "../pipeline/apiresource-meta.js";
-import { parentIdOf } from "../pipeline/steps/shapes.js";
+// The only VALUE imports from extensions/ into pipeline/ (every other
+// crossing is a type): three pure leaf modules that import nothing but
+// protos and each other, so there is no cycle. Deliberate — one resolver
+// for the tuple writer, the point-check driver and the list reader beats
+// a copy in the seam.
+import { inheritedAuthorizationParentOf } from "../pipeline/apiresource-meta.js";
+import { rowAuthorizationFactsOf } from "../pipeline/steps/authorization-facts.js";
 
 import type { CallerIdentity } from "./identity.js";
-import type { ResolvedParentLink } from "./resource-authorization.js";
+import type {
+  ResolvedParentLink,
+  RowAuthorizationFacts,
+} from "./resource-authorization.js";
 
 /**
- * The candidate metadata a post-scan lane offers the scope — the three
- * fields the cloud driver's rules key on (id for the FGA intersection,
- * labels for the guest cookie rule; org rides along for symmetry with
- * the consumer-owned intersection, so a driver can log or assert on it),
- * plus the parent for kinds whose authorization is their parent's.
+ * The candidate a post-scan lane offers the scope: the row's authorization
+ * facts (the header's last contract line), the labels the cloud driver's
+ * guest cookie rule keys on (org rides along in the facts for symmetry
+ * with the consumer-owned intersection, so a driver can log or assert on
+ * it), and the parent for kinds whose authorization is their parent's.
  */
-export interface ListEntryMeta {
-  readonly id: string;
-  readonly org: string;
+export interface ListEntryMeta extends RowAuthorizationFacts {
   readonly labels: Readonly<Record<string, string>>;
   /**
    * OPTIONAL (added 20260913.04 T04): the parent this row's authorization
    * IS — present only for a kind whose `kind_meta` is PARENT scope with
-   * INHERITED owner (the header's last contract line), the same
-   * `ResolvedParentLink` the tuple lifecycle wrote for the row. Absent for
-   * every other kind, and absent when the row's spec does not name its
-   * parent — a driver then asks about the row itself, never drops it.
+   * INHERITED owner (the header's contract line), the same
+   * `ResolvedParentLink` the tuple lifecycle wrote for the row and one of
+   * the candidate's own `parentLinks`, named again as the designation a
+   * driver may answer in place of the child. Absent for every other kind,
+   * and absent when the row's spec does not name its parent — a driver
+   * then asks about the row itself, never drops it.
    */
   readonly authorizationParent?: ResolvedParentLink;
 }
@@ -157,18 +178,21 @@ export interface ListReadScope {
 
 /**
  * The shape every stored API resource message presents to the shared
- * helper — the metadata fields the scope's candidates are built from, and
- * the spec the parent is read from (structurally, by `kind_meta`'s
+ * helper — the metadata fields the scope's candidates are built from, the
+ * spec the parents are read from (structurally, by `kind_meta`'s
  * `spec_field`; typed loosely because the field differs per kind and the
- * read is `parentIdOf`'s).
+ * read is `parentIdOf`'s), and the audit the creator stamp is read from
+ * (the one generated type every kind's status carries it as).
  */
 export interface ScopedListResource {
   metadata?: {
     id?: string;
     org?: string;
     labels?: Record<string, string>;
+    visibility?: ApiResourceVisibility;
   };
   spec?: object;
+  status?: { audit?: ApiResourceAudit };
 }
 
 /**
@@ -187,9 +211,11 @@ export interface ScopedListResource {
  *     ids. The same set either way (both are per-row predicates); the
  *     order is the header's second-to-last contract line: the scope sees
  *     the org's rows, not the kind's;
- *   - the candidates of a kind whose authorization is its parent's carry
- *     `authorizationParent` (the header's last line), resolved once per
- *     call from `kind_meta` and once per row from the spec.
+ *   - every candidate carries the row's authorization facts, and the
+ *     candidates of a kind whose authorization is its parent's name that
+ *     parent again as `authorizationParent` — one of the facts' parent
+ *     links, picked by the relation `kind_meta` declares, resolved once
+ *     per call and read once per row.
  */
 export async function restrictListByReadScope<T extends ScopedListResource>(
   scope: ListReadScope | undefined,
@@ -208,11 +234,10 @@ export async function restrictListByReadScope<T extends ScopedListResource>(
   const parentOf = authorizationParentReader(kind);
   const entries: ListEntryMeta[] = offered.map((resource) => {
     const entry: ListEntryMeta = {
-      id: resource.metadata?.id ?? "",
-      org: resource.metadata?.org ?? "",
+      ...rowAuthorizationFactsOf(kind, resource),
       labels: resource.metadata?.labels ?? {},
     };
-    const authorizationParent = parentOf(resource);
+    const authorizationParent = parentOf(entry.parentLinks);
     return authorizationParent === undefined
       ? entry
       : { ...entry, authorizationParent };
@@ -222,25 +247,22 @@ export async function restrictListByReadScope<T extends ScopedListResource>(
 }
 
 /**
- * The per-row parent reader for `kind`: a constant `undefined` for the 27
+ * The per-row parent picker for `kind`: a constant `undefined` for the 27
  * kinds whose authorization is their own, and for the kind whose
- * authorization is its parent's, the `ResolvedParentLink` the tuple
- * lifecycle wrote — or undefined for a row whose spec does not name it
- * (never a throw: a list is not a create). `kind_meta` is consulted once
- * per call, not once per row.
+ * authorization is its parent's, the link among the row's own parent
+ * links that carries the declared relation — or undefined for a row whose
+ * spec does not name it (never a throw: a list is not a create).
+ * `kind_meta` is consulted once per call, not once per row.
  */
 function authorizationParentReader(
   kind: ApiResourceKind,
-): (resource: ScopedListResource) => ResolvedParentLink | undefined {
+): (
+  parentLinks: ReadonlyArray<ResolvedParentLink>,
+) => ResolvedParentLink | undefined {
   const parent = inheritedAuthorizationParentOf(kind);
   if (parent === undefined) {
     return () => undefined;
   }
-  const parentKind = getKindEnum(parent.kind);
-  return (resource) => {
-    const parentId = parentIdOf(resource, parent.specField);
-    return parentId === ""
-      ? undefined
-      : { relation: parent.relation, parentKind, parentId };
-  };
+  return (parentLinks) =>
+    parentLinks.find((link) => link.relation === parent.relation);
 }

package/src/extensions/organization-directory.ts

@@ -5,19 +5,23 @@
  * conformance capability flags, and this port is their ONE seam:
  *
  *   - `find` (org enumeration; capability `organizationEnumeration`):
- *     single-tenant OSS enumerates freely; the cloud refuses with
- *     UNIMPLEMENTED (tenant isolation — no caller may list orgs it does
- *     not belong to).
- *   - `findMyOrganizations` (capability `multiTenant`): OSS answers ALL
- *     organizations (single-user semantics); the cloud filters to the
- *     caller's authorized set.
+ *     the trusted-local laptop enumerates freely; the cloud — and open
+ *     source under the built-in authorization posture — refuses with
+ *     UNIMPLEMENTED (no caller may list organizations they hold no role
+ *     in; `find` is skip-authorization by annotation, so the refusal is
+ *     the only thing standing between a member and every row).
+ *   - `findMyOrganizations` (capability `multiTenant`): the trusted-local
+ *     laptop answers ALL organizations (single-user semantics); the cloud
+ *     and the built-in directory filter to what the caller may view.
  *   - `getByExternalOrgId` (capability `externalOrgLookup`): deliberately
  *     absent from the OSS partial registration (UNIMPLEMENTED by
  *     construction); the cloud resolves external IdP org ids.
  *
- * No directory composed = the controller's OSS behavior, byte-identical.
- * The controller stays the ONE owner of its chains — the directory
- * answers policy questions and id lookups; it never handles RPCs.
+ * No directory composed = the trusted-local behavior, byte-identical; the
+ * built-in directory (authorization/organization-directory.ts) composes
+ * under the built-in posture, a unit's under its own. The controller stays
+ * the ONE owner of its chains — the directory answers policy questions
+ * and id lookups; it never handles RPCs.
  */
 import type { CallerIdentity } from "./identity.js";
 

package/src/extensions/resource-authorization.ts

@@ -55,6 +55,7 @@
  */
 import type { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
 import type { OwnerAttributionType } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/authorization_config_pb";
+import type { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
 import type { IamPolicy } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/api_pb";
 import type { IamPolicySpec } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/spec_pb";
 
@@ -90,6 +91,39 @@ export interface ResolvedParentLink {
   readonly parentId: string;
 }
 
+/**
+ * The facts a stored row carries that its authorization tuples derive
+ * from — the row-side vocabulary of `kind_meta.authorization`, read back
+ * from a row rather than resolved at its create. The lifecycle derives a
+ * `ResourceCreatedEvent` from the same facts on the way in; a list lane
+ * offers them on every candidate (`ListEntryMeta`, list-read-scope.ts);
+ * the built-in authorizer derives a loaded row's tuples from them. One
+ * shape, read by one structural resolver
+ * (pipeline/steps/authorization-facts.ts), so a driver that evaluates the
+ * model over a candidate needs no second read of the row.
+ *
+ * Read-side facts are lenient where the create-time resolution is strict:
+ * a legacy row that names no organization or no parent carries none (an
+ * empty `org`, a link absent from `parentLinks`) and a stamp that names
+ * nobody is the empty string — a fact about the row, never a fault of the
+ * read.
+ */
+export interface RowAuthorizationFacts {
+  readonly id: string;
+  /** `metadata.org`; "" for kinds outside organization scope and for legacy rows that never named one. */
+  readonly org: string;
+  /** `metadata.visibility` as stored; unspecified when the row never set one. */
+  readonly visibility: ApiResourceVisibility;
+  /** `status.audit.spec_audit.created_by.id` as stamped; "" when absent. Classified by the reader, not here. */
+  readonly createdBy: string;
+  /**
+   * The scope link and every configured additional parent, in the tuple
+   * lifecycle's order, from the row's own fields; a parent the row does
+   * not name is absent, never a fault.
+   */
+  readonly parentLinks: ReadonlyArray<ResolvedParentLink>;
+}
+
 /** Fired synchronously after a resource row is first persisted. */
 export interface ResourceCreatedEvent {
   readonly kind: ApiResourceKind;

package/src/extensions/schedule-fire-caller.ts

@@ -2,32 +2,63 @@
  * The schedule-fire caller seam (stigmer-cloud#572) — WHO a schedule fire
  * acts as when the RunStarter re-enters the execution create pipeline.
  *
- * OSS deliberately has no caller identity on this lane (DD-015 D-G: the
- * single-user edition has no tokens to carry one), so with no driver
- * composed every fire enters as the in-process `internal` class — today's
- * behavior, byte-identical. The cloud edition's Java baseline instead
- * mints a schedule JWT per fire (sub = the org's system-schedule account,
- * claim = the firing Schedule id) so the created session and execution
- * carry real attribution and the schedule's viewer set reaches the run
- * (the FGA model's session#schedule link — "without it a scheduled run is
- * invisible to every human, including the schedule's owner"). This seam
- * lets a composition supply that identity; the fire then propagates it
- * through the R5 caller-propagation header exactly like the other
- * request-origin in-process creates.
+ * With no driver composed a fire enters as the in-process `internal`
+ * class — the trusted-local laptop's lane, where the one caller is the
+ * server's operator and attribution has nobody to separate. Under an
+ * authentication posture that lane is wrong: the internal class carries
+ * the operator's email or `"system"`, which no enforcing evaluator
+ * recognizes as a person, so the fired session would belong to nobody
+ * (the FGA model's own words — "without it a scheduled run is invisible
+ * to every human, including the schedule's owner"). Two drivers answer
+ * it: the cloud edition mints a schedule JWT per fire (sub = the org's
+ * system-schedule account, claim = the firing Schedule id) so the run
+ * reaches the schedule's viewer set through the session#schedule link;
+ * open source, under the built-in authorization posture, makes the fire
+ * act as the schedule's CREATOR (authorization/schedule-fire-caller.ts),
+ * so the run and its session are that person's. The fire then propagates
+ * the identity through the R5 caller-propagation header exactly like the
+ * other request-origin in-process creates.
  *
  * Single-instance point. The mint is per fire — the schedule id is a
- * claim of the minted credential, never a cached field — and a mint
- * failure is an infrastructure fault: the RunStarter lets it propagate,
- * so the tick activity retries (the deterministic execution name absorbs
- * the retry) and a manual trigger surfaces the failure to its caller.
+ * claim of the minted credential, never a cached field. Two failure
+ * shapes, and the RunStarter tells them apart by type, the store-fault
+ * precedent (`ResourceNotFoundError` is checked with `instanceof`; every
+ * other fault is infrastructure):
+ *
+ *   - any other thrown error is an INFRASTRUCTURE fault: the RunStarter
+ *     lets it propagate, so the tick activity retries (the deterministic
+ *     execution name absorbs the retry) and a manual trigger surfaces
+ *     the failure to its caller;
+ *   - `ScheduleFireCallerRefusedError` is a DETERMINISTIC refusal — this
+ *     fire can act as nobody, and no retry will change that (a schedule
+ *     stamped by no person this server knows). The RunStarter answers
+ *     the `refused` outcome the way it answers a launch gate's refusal:
+ *     the failure streak counts it and pauses the schedule with the
+ *     reason, so the person who scheduled it sees why in the console
+ *     instead of a tick failing quietly forever.
  */
 import type { CallerIdentity } from "./identity.js";
 
 export interface ScheduleFireCallerMint {
   /**
    * Mints the caller identity one fire acts as. `rawToken` must carry the
-   * edition's verifiable credential for the identity (compositions read
-   * fire-scoped claims — e.g. the schedule id — from it downstream).
+   * edition's verifiable credential for the identity when the edition
+   * reads fire-scoped claims from it downstream (the cloud does — the
+   * schedule id); an edition that propagates the identity in-process and
+   * reads nothing off the token leaves it empty (open source does).
    */
   mintFireCaller(org: string, scheduleId: string): Promise<CallerIdentity>;
 }
+
+/**
+ * The mint's deterministic refusal (the module header): thrown by a
+ * driver when the fire can act as nobody and retrying cannot help. The
+ * message is the reason the schedule's status carries, so it is written
+ * for the person who scheduled the run.
+ */
+export class ScheduleFireCallerRefusedError extends Error {
+  constructor(reason: string) {
+    super(reason);
+    this.name = "ScheduleFireCallerRefusedError";
+  }
+}

package/src/identity/__tests__/oidc-verifier.test.ts

@@ -218,6 +218,28 @@ describe("the byte-pinned classifyAuthError arms", () => {
     expect(ConnectError.from(error).code).toBe(Code.Unauthenticated);
     expect(ConnectError.from(error).rawMessage).toBe(INVALID_TOKEN_MESSAGE);
   });
+
+  it("a JWT whose algorithm the JWKS cannot serve (HS256 against RS256 keys) → 'invalid token', a CREDENTIAL rejection, never a plain error the chassis maps INTERNAL", async () => {
+    // The shape the server's own execution-scoped runner token has
+    // (runnerauth.ts). Whether this verifier should ever SEE it is the
+    // chain order's business (the runner verifier claims it first); that
+    // it must not answer INTERNAL when it does is this arm's. Until
+    // 2026-09-16 it threw jose's JOSENotSupported unclassified, and a
+    // self-host with sign-in on failed every agent execution with
+    // "internal server error" (stigmer#1137).
+    const segment = (value: unknown): string =>
+      Buffer.from(JSON.stringify(value)).toString("base64url");
+    const hs256 = `${segment({ alg: "HS256", typ: "JWT" })}.${segment({
+      token_type: "execution_scoped",
+      execution_id: "aex_1",
+      iat: 1,
+      exp: 4102444800,
+    })}.${segment("a-mac-this-verifier-cannot-check")}`;
+    const error = await rejectionOf(verifier().verify(hs256));
+    expect(error).toBeInstanceOf(ConnectError);
+    expect(ConnectError.from(error).code).toBe(Code.Unauthenticated);
+    expect(ConnectError.from(error).rawMessage).toBe(INVALID_TOKEN_MESSAGE);
+  });
 });
 
 describe("subject → account resolution (20260911.11 Q-IA-2, A1)", () => {

package/src/identity/oidc-verifier.ts

@@ -159,7 +159,14 @@ function classifyJoseError(error: unknown): unknown {
   }
   if (
     error instanceof joseErrors.JWTInvalid ||
-    error instanceof joseErrors.JWSInvalid
+    error instanceof joseErrors.JWSInvalid ||
+    // A JWT whose algorithm the issuer's key set cannot serve (an HS256
+    // token against an RS256 JWKS): a credential this verifier recognizes
+    // but cannot verify, so a credential rejection — never the
+    // infrastructure arm. Until 2026-09-16 it fell through to INTERNAL,
+    // and a self-host with sign-in on failed every agent execution on its
+    // own runner token (stigmer#1137).
+    error instanceof joseErrors.JOSENotSupported
   ) {
     return new ConnectError(INVALID_TOKEN_MESSAGE, Code.Unauthenticated);
   }

package/src/index.ts

@@ -148,14 +148,64 @@ export type { AuthorizationQueryEngine } from "./extensions/authorization-querie
 export type { IdentityFederation } from "./extensions/identity-federation.js";
 export type { AccountsBySubject } from "./domain/identityaccount/resolve.js";
 export { identityIdForSubject } from "./domain/identityaccount/resolve.js";
+// The built-in authorizer's model seams: the kind
+// declarations (transcripts of the cloud's `.fga` files), the evaluator,
+// and the OpenFGA store-test kit — exported so the cloud's drift test
+// compares the live model against the transcripts and runs its live
+// store tests through the evaluator, both from the published package.
+// The drivers themselves are composed by the root and are not exported.
+export type {
+  DerivedRelation,
+  KindDeclaration,
+  Rewrite,
+  SubjectType,
+} from "./authorization/model/rewrite.js";
+export type { Model } from "./authorization/model/index.js";
+export {
+  builtInModel,
+  declarationFor,
+  newModel,
+} from "./authorization/model/index.js";
+export type {
+  CheckContext,
+  ObjectRef,
+  Person,
+  Subject,
+  Tuple,
+  TupleSource,
+} from "./authorization/tuples.js";
+export type { EvaluationFault } from "./authorization/evaluator.js";
+export {
+  AuthorizationEvaluationError,
+  MAX_RESOLUTION_DEPTH,
+  checkRelation,
+} from "./authorization/evaluator.js";
+export type {
+  StoreTestCase,
+  StoreTestDocument,
+  StoreTestKit,
+  StoreTestSkip,
+  StoreTestSkipReason,
+} from "./authorization/store-test-kit.js";
+export {
+  parseStoreTestDocument,
+  storeTestCases,
+} from "./authorization/store-test-kit.js";
+// The kinds whose missing row the built-in authorizer denies instead of
+// answering not-found — the cloud's probe exemption over the open-source
+// tier; exported so the cloud's drift test pins the two sets equal.
+export { NOT_FOUND_EXEMPT_KINDS } from "./authorization/authorizer.js";
 export type {
   ListReadScope,
   ListEntryMeta,
 } from "./extensions/list-read-scope.js";
 // The stigmer-cloud#572 seam: the identity a schedule fire acts as
 // (drivers.scheduleFireCaller) — the composition mints it per fire; the
-// RunStarter propagates it through the R5 in-process header.
+// RunStarter propagates it through the R5 in-process header. A mint that
+// can act as nobody throws the seam's typed refusal, which the RunStarter
+// counts against the schedule instead of retrying.
 export type { ScheduleFireCallerMint } from "./extensions/schedule-fire-caller.js";
+export { ScheduleFireCallerRefusedError } from "./extensions/schedule-fire-caller.js";
 // The 20260830.03 seam: the visitor-sanitization policy the serving
 // chain's error boundary consumes (drivers.visitorErrorPolicy) — the
 // composition supplies WHO is on the anonymous surface and WHAT copy

package/src/pipeline/__tests__/kind-by-id-prefix.test.ts

@@ -0,0 +1,75 @@
+/**
+ * Pins `kindByIdPrefix` (pipeline/apiresource-meta.ts), the inverse of
+ * `getIdPrefix` over the ids the server mints (`<prefix>_<ulid>`,
+ * pipeline/steps/defaults.ts). The runner-credential lane reads it to
+ * learn which execution kind a token's binding names — an agent
+ * execution (`aex_`) or a workflow execution (`wex_`) — without a second
+ * claim on the token or a guess.
+ *
+ * Two properties are load-bearing:
+ *
+ *   - NEVER a throw. The id arrives inside a credential; the caller
+ *     refuses with its own sentence, so anything that is not a known
+ *     prefix followed by an underscore is the unknown kind.
+ *   - Every `id_prefix` in the contract is UNIQUE. The lookup is a Map
+ *     over the `kind_meta` table; a duplicate prefix would silently win
+ *     for one kind and lose for the other. The pin below turns a future
+ *     duplicate into a reviewed change.
+ */
+import { describe, expect, it } from "vitest";
+
+import {
+  ApiResourceKind,
+  ApiResourceKindSchema,
+  kind_meta,
+} from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { getOption, hasOption } from "@bufbuild/protobuf";
+
+import { getIdPrefix, kindByIdPrefix } from "../apiresource-meta.js";
+
+describe("kindByIdPrefix — a minted id names its kind by prefix", () => {
+  it.each([
+    ["aex_01m2mp45efcjvq2z1e1yn4cyz7", ApiResourceKind.agent_execution],
+    ["wex_01m2mp45efcjvq2z1e1yn4cyz7", ApiResourceKind.workflow_execution],
+    ["ses_x", ApiResourceKind.session],
+    ["ida_carol", ApiResourceKind.identity_account],
+  ])("%s is %s", (id, kind) => {
+    expect(kindByIdPrefix(id)).toBe(kind);
+  });
+
+  it.each([
+    ["zzz_unknown_kind", "an unknown prefix"],
+    ["aex", "a prefix with no underscore"],
+    ["_aex", "a leading underscore names no prefix"],
+    ["", "empty"],
+    ["AEX_upper", "prefixes are lowercase in the contract"],
+    ["stk_notajwt", "an API key's prefix is not a kind"],
+  ])("%s is the unknown kind (%s) — never a throw", (id) => {
+    expect(kindByIdPrefix(id)).toBe(ApiResourceKind.api_resource_kind_unknown);
+  });
+
+  it("round-trips with getIdPrefix over every kind the contract declares", () => {
+    for (const value of ApiResourceKindSchema.values) {
+      if (!hasOption(value, kind_meta)) continue;
+      const kind = value.number as ApiResourceKind;
+      expect(kindByIdPrefix(`${getIdPrefix(kind)}_01anyulid`), value.name).toBe(
+        kind,
+      );
+    }
+  });
+
+  it("every id_prefix in the contract is unique — the table pin a duplicate must change", () => {
+    const seen = new Map<string, string>();
+    for (const value of ApiResourceKindSchema.values) {
+      if (!hasOption(value, kind_meta)) continue;
+      const prefix = getOption(value, kind_meta).idPrefix;
+      expect(prefix, `${value.name} declares no id_prefix`).not.toBe("");
+      const holder = seen.get(prefix);
+      expect(
+        holder,
+        `id_prefix '${prefix}' is declared by both ${holder} and ${value.name}`,
+      ).toBeUndefined();
+      seen.set(prefix, value.name);
+    }
+  });
+});

package/src/pipeline/__tests__/router-transport.test.ts

@@ -157,9 +157,7 @@ describe("R5: caller propagation through the in-process transport", () => {
         },
       },
     );
-    expect(seen).toEqual([
-      { ...caller, origin: "in-process" },
-    ]);
+    expect(seen).toEqual([{ ...caller, origin: "in-process" }]);
   });
 
   it("mints the internal class when nothing was propagated (the daemon default)", async () => {

package/src/pipeline/apiresource-labels.ts

@@ -8,9 +8,12 @@
  * instances) but never to GRANT anything. Where a grant-shaped decision is
  * needed, key it on server-owned state instead (e.g. the parent blueprint's
  * status.default_instance_id, written only by the create/self-heal flows).
- * The cloud edition additionally guards the whole reserved namespace at its
- * write boundaries (GuardReservedLabelsStep); OSS has no such guard, which
- * is one of the reasons OSS predicates must not trust these labels alone.
+ * Every write boundary runs GuardReservedLabels over the namespace
+ * (pipeline/steps/guard-reserved-labels.ts), but the open-source
+ * authorizer's permissive default ALLOWS reserved-label writes by design
+ * (the self-hosted operator owns the store), which is why a restrict-shaped
+ * predicate here still pairs the label with server-owned state: the
+ * plugin-managed guard refuses only beside an existing plugin row.
  */
 import type { ApiResourceMetadata } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
 
@@ -44,6 +47,31 @@ export const SYSTEM_MANAGED_LABEL = `${RESERVED_LABEL_PREFIX}system-managed`;
  */
 export const RESERVED_LABEL_TRUE = "true";
 
+/**
+ * The plugin that materialised a resource: the label's value is the
+ * plugin's id (`plg_...`), never its slug, because `findAllByLabel` is
+ * org-agnostic and two organizations may both install `thermos`. Written
+ * only by the plugin controller (in-process, as the installing caller);
+ * membership is derived on read from it and stored nowhere else.
+ */
+export const PLUGIN_LABEL = `${RESERVED_LABEL_PREFIX}plugin`;
+
+/**
+ * The archive digest a member was last materialised from — the per-child
+ * convergence marker. A re-push compares every member's value with the
+ * head's digest before deciding it has nothing to do, so a member another
+ * lane deleted or an older install left behind is re-materialised.
+ */
+export const PLUGIN_VERSION_LABEL = `${RESERVED_LABEL_PREFIX}plugin-version`;
+
+/** The plugin id a resource's labels claim, or undefined when unlabelled. */
+export function pluginIdOf(
+  metadata: ApiResourceMetadata | undefined,
+): string | undefined {
+  const value = metadata?.labels[PLUGIN_LABEL];
+  return value === undefined || value === "" ? undefined : value;
+}
+
 /**
  * Whether the metadata carries the DEFAULT_INSTANCE_LABEL marker
  * (undefined-safe) — Go IsDefaultInstance.

package/src/pipeline/apiresource-meta.ts

@@ -351,3 +351,44 @@ function kindsByEnumName(): Map<string, ApiResourceKind> {
   }
   return enumNameCache;
 }
+
+/**
+ * The kind a minted resource id belongs to, read off its prefix — the
+ * inverse of `getIdPrefix` over the ids `generateId` mints
+ * (`<prefix>_<ulid>`, pipeline/steps/defaults.ts). The one consumer today
+ * is the runner-credential lane, whose token binds an execution by id and
+ * must know whether that id names an agent execution or a workflow
+ * execution without a second claim or a guess. Anything that is not
+ * `<known prefix>_<rest>` — no underscore, an unknown prefix, the empty
+ * string — is `api_resource_kind_unknown`; never a throw, because the id
+ * arrived inside a credential and the caller refuses with its own
+ * sentence. Every `id_prefix` in the contract is unique; the table pin in
+ * __tests__ makes a future duplicate a reviewed change, since this lookup
+ * would otherwise resolve it silently to one of the two.
+ */
+export function kindByIdPrefix(id: string): ApiResourceKind {
+  const separator = id.indexOf("_");
+  if (separator <= 0) {
+    return ApiResourceKind.api_resource_kind_unknown;
+  }
+  return (
+    kindsByIdPrefix().get(id.slice(0, separator)) ??
+    ApiResourceKind.api_resource_kind_unknown
+  );
+}
+
+let idPrefixCache: Map<string, ApiResourceKind> | undefined;
+
+function kindsByIdPrefix(): Map<string, ApiResourceKind> {
+  if (idPrefixCache === undefined) {
+    idPrefixCache = new Map(
+      ApiResourceKindSchema.values
+        .filter((value) => hasOption(value, kind_meta))
+        .map((value) => [
+          getOption(value, kind_meta).idPrefix,
+          value.number as ApiResourceKind,
+        ]),
+    );
+  }
+  return idPrefixCache;
+}