@stigmer/server 3.14.0-dev.20260910084630

package/src/extensions/__tests__/secret-cleanup-composed.test.ts

@@ -0,0 +1,356 @@
+/**
+ * Pins the Q7 secret-cleanup wiring END TO END (convergence 20260830.04
+ * Stage 3): a composed server with an extension-registered fake "v9"
+ * codec (write version v9, so every sealed value has recordable backing
+ * state) proves, through real gRPC calls, that:
+ *
+ *   - the three delete chains (environment, oauthapp, channelapp)
+ *     destroy exactly the doomed resource's sealed values;
+ *   - the environment update chain destroys ONLY dropped keys — a
+ *     rotated key keeps its backing state (superseded versions age out
+ *     via the store's retention, the Java posture), and marker-preserved
+ *     keys are untouched;
+ *   - removeVariables destroys the removed keys and ignores unknowns;
+ *     the updateVariables merge lane destroys nothing;
+ *   - a destroy failure NEVER fails the request (best-effort after the
+ *     store write);
+ *   - the composed facade rides ComposedServer.secrets (gate ruling G2)
+ *     — the same instance the domains sealed with.
+ *
+ * The v1-only default arm (cleanup as a silent no-op) is pinned by the
+ * conformance rosters; the unit-level contract lives in
+ * pipeline/steps/__tests__/secret-cleanup.test.ts.
+ */
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import { createClient } from "@connectrpc/connect";
+import type { Client, Transport } from "@connectrpc/connect";
+import { createGrpcTransport } from "@connectrpc/connect-node";
+import {
+  afterAll,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  vi,
+} from "vitest";
+
+import { ChannelAppSchema } from "@stigmer/protos/ai/stigmer/agentic/channelapp/v1/api_pb";
+import { ChannelAppCommandController } from "@stigmer/protos/ai/stigmer/agentic/channelapp/v1/command_pb";
+import { EnvironmentSchema } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/api_pb";
+import { EnvironmentCommandController } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/command_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { OAuthAppSchema } from "@stigmer/protos/ai/stigmer/iam/oauthapp/v1/api_pb";
+import { OAuthAppCommandController } from "@stigmer/protos/ai/stigmer/iam/oauthapp/v1/command_pb";
+
+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 type { SecretCodec } from "../../encryption/codec.js";
+import type { EncryptionScope } from "../../encryption/encryption.js";
+import { REDACTED_MARKER } from "../../encryption/encryption.js";
+import { ResourceNotFoundError } from "../../store/interface.js";
+
+const silentLogger = createLogger({
+  level: "error",
+  pretty: false,
+  write: () => {},
+});
+
+const TEST_KEY_B64 = Buffer.alloc(32, 9).toString("base64");
+const ORG = "acme";
+
+/** The recordable backing state: delete() logs calls; failNext arms throws. */
+class RecordingCodec implements SecretCodec {
+  readonly version = "v9";
+  readonly deleted: string[] = [];
+  readonly failNext: Error[] = [];
+
+  async encrypt(plaintext: string, _scope: EncryptionScope): Promise<string> {
+    return `enc:v9:${Buffer.from(plaintext, "utf8").toString("base64")}`;
+  }
+
+  async decrypt(encrypted: string): Promise<string> {
+    return Buffer.from(encrypted.slice("enc:v9:".length), "base64").toString(
+      "utf8",
+    );
+  }
+
+  async delete(storedValue: string): Promise<void> {
+    const failure = this.failNext.shift();
+    if (failure !== undefined) {
+      throw failure;
+    }
+    this.deleted.push(storedValue);
+  }
+}
+
+const codec = new RecordingCodec();
+
+let server: ComposedServer;
+let dir: string;
+let envCommand: Client<typeof EnvironmentCommandController>;
+let oauthCommand: Client<typeof OAuthAppCommandController>;
+let channelCommand: Client<typeof ChannelAppCommandController>;
+
+beforeAll(async () => {
+  dir = mkdtempSync(path.join(tmpdir(), "secret-cleanup-composed-"));
+  vi.stubEnv("STIGMER_ENCRYPTION_KEY", TEST_KEY_B64);
+  // The composition posture under test: extension codec v9 IS the write
+  // version, so freshly sealed values carry recordable backing state.
+  vi.stubEnv("STIGMER_ENCRYPTION_WRITE_VERSION", "v9");
+  server = await composeServer({
+    config: loadConfig({
+      STIGMER_MODEL_REGISTRY_REFRESH: "off",
+      TEMPORAL_HOST_PORT: "127.0.0.1:1",
+      DB_PATH: path.join(dir, "stigmer.db"),
+      STORAGE_PATH: path.join(dir, "storage"),
+      ARTIFACT_LOCAL_BASE_PATH: path.join(dir, "artifacts"),
+    }),
+    logger: silentLogger,
+    extensions: [
+      {
+        name: "fake-secret-codecs",
+        drivers: {
+          secretCodecs: new Map<string, SecretCodec>([["v9", codec]]),
+        },
+      },
+    ],
+    portOverride: 0,
+    host: "127.0.0.1",
+  });
+  const port = await server.start();
+  const transport: Transport = createGrpcTransport({
+    baseUrl: `http://127.0.0.1:${port}`,
+  });
+  envCommand = createClient(EnvironmentCommandController, transport);
+  oauthCommand = createClient(OAuthAppCommandController, transport);
+  channelCommand = createClient(ChannelAppCommandController, transport);
+});
+
+afterAll(async () => {
+  await server.shutdown();
+  rmSync(dir, { recursive: true, force: true });
+  vi.unstubAllEnvs();
+});
+
+beforeEach(() => {
+  codec.deleted.length = 0;
+  codec.failNext.length = 0;
+});
+
+let counter = 0;
+function envInput(
+  data: Record<string, { value: string; isSecret: boolean }>,
+  name?: string,
+) {
+  counter += 1;
+  return {
+    apiVersion: "agentic.stigmer.ai/v1",
+    kind: "Environment",
+    metadata: { name: name ?? `Cleanup Env ${counter}`, org: ORG },
+    spec: { description: "secret-cleanup composed pin", data },
+  };
+}
+
+async function storedEnvData(id: string): Promise<Record<string, string>> {
+  const env = await server.store.getResource(
+    ApiResourceKind.environment,
+    id,
+    EnvironmentSchema,
+  );
+  return Object.fromEntries(
+    Object.entries(env.spec?.data ?? {}).map(([k, v]) => [k, v.value]),
+  );
+}
+
+describe("the composed facade exposure (gate ruling G2)", () => {
+  it("ComposedServer.secrets is the instance the domains sealed with", async () => {
+    const created = await envCommand.create(
+      envInput({ TOKEN: { value: "open-sesame", isSecret: true } }),
+    );
+    const stored = await storedEnvData(created.metadata!.id);
+    expect(stored["TOKEN"]).toMatch(/^enc:v9:/);
+    expect(await server.secrets.decrypt(stored["TOKEN"]!)).toBe("open-sesame");
+  });
+});
+
+describe("delete chains destroy sealed backing state", () => {
+  it("environment delete destroys every sealed value, never the plain ones", async () => {
+    const created = await envCommand.create(
+      envInput({
+        FIRST: { value: "secret-one", isSecret: true },
+        SECOND: { value: "secret-two", isSecret: true },
+        PLAIN: { value: "visible", isSecret: false },
+      }),
+    );
+    const stored = await storedEnvData(created.metadata!.id);
+
+    await envCommand.delete({ resourceId: created.metadata!.id });
+
+    expect([...codec.deleted].sort()).toEqual(
+      [stored["FIRST"]!, stored["SECOND"]!].sort(),
+    );
+  });
+
+  it("oauthapp delete destroys the sealed client secret", async () => {
+    counter += 1;
+    const created = await oauthCommand.create({
+      apiVersion: "iam.stigmer.ai/v1",
+      kind: "OAuthApp",
+      metadata: { name: `Cleanup Vendor ${counter}`, org: ORG },
+      spec: {
+        provider: "TestVendor",
+        clientId: "client-id",
+        clientSecret: "vendor-client-secret",
+        authorizationUrl: "https://vendor.example.com/oauth/authorize",
+        tokenUrl: "https://vendor.example.com/oauth/token",
+        scopes: ["read"],
+      },
+    });
+    const storedApp = await server.store.getResource(
+      ApiResourceKind.oauth_app,
+      created.metadata!.id,
+      OAuthAppSchema,
+    );
+    const sealed = storedApp.spec!.clientSecret;
+    expect(sealed).toMatch(/^enc:v9:/);
+
+    await oauthCommand.delete({ resourceId: created.metadata!.id });
+
+    expect(codec.deleted).toEqual([sealed]);
+  });
+
+  it("channelapp delete destroys the provider arm's sealed fields", async () => {
+    counter += 1;
+    const created = await channelCommand.create({
+      apiVersion: "agentic.stigmer.ai/v1",
+      kind: "ChannelApp",
+      metadata: { name: `Cleanup Slack ${counter}`, org: ORG },
+      spec: {
+        providerConfig: {
+          case: "slack" as const,
+          value: {
+            clientId: "1234.5678",
+            clientSecret: "shh-client-secret",
+            signingSecret: "shh-signing-secret",
+          },
+        },
+      },
+    });
+    const storedApp = await server.store.getResource(
+      ApiResourceKind.channel_app,
+      created.metadata!.id,
+      ChannelAppSchema,
+    );
+    const slack =
+      storedApp.spec?.providerConfig.case === "slack"
+        ? storedApp.spec.providerConfig.value
+        : undefined;
+    expect(slack).toBeDefined();
+
+    await channelCommand.delete({ resourceId: created.metadata!.id });
+
+    expect([...codec.deleted].sort()).toEqual(
+      [slack!.clientSecret, slack!.signingSecret].sort(),
+    );
+  });
+
+  it("a destroy failure never fails the delete (best-effort after the row is gone)", async () => {
+    const created = await envCommand.create(
+      envInput({ DOOMED: { value: "secret", isSecret: true } }),
+    );
+    codec.failNext.push(new Error("vault is down"));
+
+    await expect(
+      envCommand.delete({ resourceId: created.metadata!.id }),
+    ).resolves.toBeDefined();
+
+    await expect(
+      server.store.getResource(
+        ApiResourceKind.environment,
+        created.metadata!.id,
+        EnvironmentSchema,
+      ),
+    ).rejects.toBeInstanceOf(ResourceNotFoundError);
+    expect(codec.deleted).toEqual([]);
+  });
+});
+
+describe("environment update and variable lanes", () => {
+  it("update destroys ONLY dropped keys; marker-preserved keys are untouched", async () => {
+    const name = `Cleanup Env Drop ${++counter}`;
+    const created = await envCommand.create(
+      envInput(
+        {
+          DROPPED: { value: "goes-away", isSecret: true },
+          KEPT: { value: "stays", isSecret: true },
+        },
+        name,
+      ),
+    );
+    const before = await storedEnvData(created.metadata!.id);
+
+    await envCommand.update(
+      envInput({ KEPT: { value: REDACTED_MARKER, isSecret: true } }, name),
+    );
+
+    expect(codec.deleted).toEqual([before["DROPPED"]!]);
+    const after = await storedEnvData(created.metadata!.id);
+    expect(after["KEPT"]).toBe(before["KEPT"]);
+    expect(after["DROPPED"]).toBeUndefined();
+  });
+
+  it("a rotated key is NOT a drop — its old backing state survives", async () => {
+    const name = `Cleanup Env Rotate ${++counter}`;
+    const created = await envCommand.create(
+      envInput({ KEY: { value: "old-secret", isSecret: true } }, name),
+    );
+
+    await envCommand.update(
+      envInput({ KEY: { value: "new-secret", isSecret: true } }, name),
+    );
+
+    expect(codec.deleted).toEqual([]);
+    const after = await storedEnvData(created.metadata!.id);
+    expect(await server.secrets.decrypt(after["KEY"]!)).toBe("new-secret");
+  });
+
+  it("removeVariables destroys the removed keys, ignoring unknown keys", async () => {
+    const created = await envCommand.create(
+      envInput({
+        REMOVED: { value: "goes-away", isSecret: true },
+        SURVIVOR: { value: "stays", isSecret: true },
+      }),
+    );
+    const before = await storedEnvData(created.metadata!.id);
+
+    await envCommand.removeVariables({
+      environmentId: created.metadata!.id,
+      keys: ["REMOVED", "GHOST"],
+    });
+
+    expect(codec.deleted).toEqual([before["REMOVED"]!]);
+    const after = await storedEnvData(created.metadata!.id);
+    expect(after["SURVIVOR"]).toBe(before["SURVIVOR"]);
+  });
+
+  it("the updateVariables merge lane destroys nothing (an overwrite keeps its path)", async () => {
+    const created = await envCommand.create(
+      envInput({ KEY: { value: "old-secret", isSecret: true } }),
+    );
+
+    await envCommand.updateVariables({
+      environmentId: created.metadata!.id,
+      variables: { KEY: { value: "rotated", isSecret: true } },
+    });
+
+    expect(codec.deleted).toEqual([]);
+    const after = await storedEnvData(created.metadata!.id);
+    expect(await server.secrets.decrypt(after["KEY"]!)).toBe("rotated");
+  });
+});

package/src/extensions/authorizer.ts

@@ -0,0 +1,64 @@
+/**
+ * The Authorizer extension point — the one authorization decision seam of
+ * the convergence blueprint (20260826.02 blueprint/03 §5, DD-007), carried
+ * by the extension registry from O1 (20260826.09) and CONSUMED by O2,
+ * which splices the shared Authorize step at position 1 of every chain and
+ * installs the OSS permissive single-team default.
+ *
+ * The interface is transcribed verbatim from the ratified design. The
+ * `unavailable` arm is deliberate: the Java StepResult distinguishes
+ * denial from evaluation error so an authorization-backend outage surfaces
+ * as an INTERNAL fault, never a silent lockout dressed as
+ * PERMISSION_DENIED. An interface without that distinction would be wrong
+ * on day one — the deny/unavailable mapping is wire contract (deny →
+ * PERMISSION_DENIED; unavailable → INTERNAL), unit-tested both arms when
+ * O2 lands the step.
+ */
+import type { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import type { IamPermission } from "@stigmer/protos/ai/stigmer/iam/v1/enum_pb";
+
+import type { CallerIdentity } from "./identity.js";
+
+/**
+ * One authorization check: may `caller` exercise `permission` on the named
+ * resource? Permission names are the shared IamPermission enum verbatim —
+ * in the cloud they are the FGA relation vocabulary.
+ */
+export interface AuthzCheck {
+  readonly permission: IamPermission;
+  readonly resourceKind: ApiResourceKind;
+  readonly resourceId: string;
+}
+
+/**
+ * The decision arms (blueprint §5a — deny and unavailable are distinct).
+ *
+ * `not-found` is the C2 ruling-Q1 refinement (DD-007 addendum,
+ * 20260827.10): for RESOURCE-SCOPED checks, an authorizer that has
+ * verified the target does not exist answers not-found instead of deny —
+ * the Authorize step maps it to NOT_FOUND with the domain copy, matching
+ * the Java edition's deliberate load-before-authorize order
+ * (stigmer#224: a nonexistent id answers NOT_FOUND, never
+ * PERMISSION_DENIED). Only meaningful with a known kind and a non-empty
+ * resource id — anything else is an authorizer contract bug and surfaces
+ * as INTERNAL. The OSS permissive default never emits it.
+ */
+export type AuthzDecision =
+  | { readonly kind: "allow" }
+  /** A genuine denial — maps to PERMISSION_DENIED on the wire. */
+  | { readonly kind: "deny"; readonly reason: string }
+  /** The resource-scoped target does not exist — maps to NOT_FOUND. */
+  | { readonly kind: "not-found" }
+  /** An evaluation failure — maps to INTERNAL on the wire, never a denial. */
+  | { readonly kind: "unavailable"; readonly cause: Error };
+
+/**
+ * The pure decision interface. Exactly ONE implementation is composed per
+ * server (the resolver enforces it): OSS's permissive single-team default
+ * (O2) or an extension's (the cloud registers OpenFGA). Write concerns —
+ * tuple seeding on create — are NOT authorization checks; they ride the
+ * post-persist gate slots (blueprint §5b item 4).
+ */
+export interface Authorizer {
+  authorize(caller: CallerIdentity, check: AuthzCheck): Promise<AuthzDecision>;
+}

package/src/extensions/caller-guards.ts

@@ -0,0 +1,61 @@
+/**
+ * The post-authentication caller-guard seam (convergence entry
+ * 20260902.02, gate ruling Q1) — enforcement of the MINTING CLIENT's
+ * contract, run by the serving chassis after the position-1 identity
+ * stamp. The TS rendering of the cloud Java
+ * PlatformClientEnforcementInterceptor's home: verification says who the
+ * caller IS (the IdentityVerifier chain, deliberately token-only); a
+ * guard says whether the client that minted the credential may still be
+ * served (deletion-revocation liveness, cloud#342; Origin vs
+ * allowed_origins, oss#375). Java separates the two classes the same way.
+ *
+ * List point — guards concatenate in unit order and run in composed
+ * order; the first throw wins. OSS composes zero guards, so with none
+ * registered the serving chain behaves byte-identically to before the
+ * point existed (the conformance rosters pin that).
+ *
+ * The in-process exemption is STRUCTURAL, not policed: guards are a
+ * parameter of the serving chain's identity source only
+ * (createVerifierChainInterceptor); the in-process interceptor has no
+ * guard parameter to forget — the TS rendering of the Java
+ * InProcessCallContextHolder skip.
+ *
+ * Skip logic is the guard's own business. OSS runs every composed guard
+ * on every serving request with the FINAL stamped identity (claimed or
+ * trusted-local): which tokens a guard exempts (claim-less tokens, the
+ * load-bearing token_type skip, health/reflection services) is edition
+ * policy, decoded by the guard from CallerIdentity.rawToken — never OSS
+ * type widening (the O5 Q4 vocabulary doctrine).
+ *
+ * Fault doctrine (the verifier-chain doctrine applied to admission): a
+ * guard that REFUSES throws a ConnectError — its own wire mapping, and
+ * deliberate-refusal codes pass the position-0 error boundary untouched,
+ * so byte-pinned refusal copy survives to the wire. Any other throw is
+ * an infrastructure fault — INTERNAL, never softened into a denial (a
+ * store outage during a liveness read must not read as "client
+ * deleted"). The chassis logs both arms with the guard's name: position
+ * 1 sits outside the logging interceptor, so a guard's refusal would
+ * otherwise leave no operator record.
+ */
+import type { DescMethod } from "@bufbuild/protobuf";
+
+import type { CallerIdentity } from "./identity.js";
+
+export interface CallerGuard {
+  /** Names the guard in refusal and fault logs (e.g. 'platform-client'). */
+  readonly name: string;
+  /**
+   * Admits by returning; refuses by throwing a ConnectError (the guard's
+   * own wire mapping). Runs on unary AND stream calls, once per call at
+   * admission, before the handler and before validation. `method` carries
+   * its parent service descriptor (service-level skips need no extra
+   * parameter); `headers` is the request's wire metadata (the Origin
+   * check reads the plain lowercase `origin` key, the verified
+   * guest-mint-lane idiom).
+   */
+  guard(
+    caller: CallerIdentity,
+    method: DescMethod,
+    headers: Headers,
+  ): Promise<void>;
+}

package/src/extensions/drivers.ts

@@ -0,0 +1,146 @@
+/**
+ * The drivers extension point — infrastructure substitution seams of the
+ * convergence blueprint (20260826.02 blueprint/03 §6, DD-006 §2a). The
+ * point exists from O1 (20260826.09); the registrable KINDS join with
+ * their extraction entries, each adding a field here as an owner-visible
+ * surface change:
+ *
+ *   - model-catalog provider (§6a) and artifact-storage driver
+ *     registration + runner-credential provider (§6b/§6c) — landed, O5
+ *     (20260827.02)
+ *   - sandbox provisioners (§6d) — landed, O6 (20260827.05)
+ *   - resource-authorization lifecycle + organization directory —
+ *     landed with C2 (20260827.10, rulings Q2/Q7)
+ *   - channel runtime (DD-004's serving seam) — landed with C3
+ *     (20260827.11, plan-gate ruling Q1)
+ *   - list read scope (the list-shaped tenant-isolation fork) — landed
+ *     with 20260830.01.sp.list-read-scoping, generalizing C2 Stage 4's
+ *     ExecutionReadScope (absorbed, gate ruling Q2)
+ *   - visitor error policy (the transport-boundary sanitizer's
+ *     edition semantics) — landed with 20260830.03, gate ruling Q1
+ *   - secret codecs (the versioned secret-value wire formats) — landed
+ *     with 20260830.04 Stage 1, gate ruling Q2
+ *   - schedule-fire caller (who a schedule fire acts as) — landed with
+ *     the stigmer-cloud#572 fix (the Java schedule-token mechanism's
+ *     seam; ruled 2026-09-01)
+ *
+ * Merge rules (enforced by resolveExtensions, DD-006 §2b): the two
+ * provider kinds are single-instance points — a second declaring unit is
+ * a boot throw naming both units (the authorizer rule); artifact-storage
+ * and sandbox-provisioner drivers merge as name-keyed maps — a
+ * duplicated name, or a name shadowing a built-in, is a boot throw (the
+ * gateSteps rule: a registration the factory could never reach must fail
+ * loudly, not sit dark). OSS defaults install at the boot/compose.ts
+ * consumption sites, never here (the default-lives-with-the-consumer
+ * doctrine).
+ */
+import type { ArtifactStorageDriverFactory } from "../artifactstorage/artifact-storage.js";
+import type { ChannelRuntime } from "../domain/agentchannel/channel-runtime.js";
+import type { SecretCodec } from "../encryption/codec.js";
+import type { ModelCatalogProvider } from "../domain/workflow/registry/model-catalog-provider.js";
+import type { VisitorErrorPolicy } from "../pipeline/interceptors/error-boundary.js";
+import type { RunnerCredentialProvider } from "../runnerauth/runner-credential-provider.js";
+import type { SandboxProvisionerFactory } from "../sandbox/provisioner.js";
+import type { ListReadScope } from "./list-read-scope.js";
+import type { OrganizationDirectory } from "./organization-directory.js";
+import type { ResourceAuthorizationLifecycle } from "./resource-authorization.js";
+import type { ScheduleFireCallerMint } from "./schedule-fire-caller.js";
+
+/** The driver contributions of one extension unit. */
+export interface ExtensionDrivers {
+  /**
+   * The model-catalog data source (DD-008; single-instance point). When
+   * composed, it replaces the OSS ModelRegistryStore everywhere — the
+   * OSS store and its upstream refresh are then never constructed.
+   */
+  readonly modelCatalogProvider?: ModelCatalogProvider;
+  /**
+   * The runner-credential mint/verify seam (§6c; single-instance point).
+   * When composed, it replaces the OSS execution-scoped HS256 default at
+   * every consumer (platform exchange, mcpserver connect, the
+   * executioncontext decrypt lane).
+   */
+  readonly runnerCredentialProvider?: RunnerCredentialProvider;
+  /**
+   * Blob-storage backends registrable by name (§6b), selectable through
+   * the ARTIFACT_STORAGE_TYPE / SKILL_ARTIFACT_STORAGE_TYPE config knobs.
+   * Factories, not instances — an unselected driver constructs nothing.
+   */
+  readonly artifactStorageDrivers?: ReadonlyMap<
+    string,
+    ArtifactStorageDriverFactory
+  >;
+  /**
+   * Sandbox provisioners registrable by name (§6d), selectable through
+   * the SANDBOX_PROVISIONER_TYPE config knob. Factories, not instances —
+   * an unselected driver constructs nothing. The built-in names
+   * (local-process, docker, kubernetes — src/sandbox/provisioner.ts) are
+   * reserved.
+   */
+  readonly sandboxProvisionerDrivers?: ReadonlyMap<
+    string,
+    SandboxProvisionerFactory
+  >;
+  /**
+   * The resource-authorization lifecycle seam (C2, ruling Q2;
+   * single-instance point). When composed, the three shared tuple steps
+   * (CreateAuthorizationTuples / CleanupIamPolicies /
+   * UpdateVisibilityTuples) deliver resolved events to it; when absent,
+   * those steps no-op — OSS behavior byte-identical.
+   */
+  readonly resourceAuthorizationLifecycle?: ResourceAuthorizationLifecycle;
+  /**
+   * The organization query directory (C2, ruling Q7; single-instance
+   * point). When composed, the organization controller consults it for
+   * the three edition forks (enumeration posture, my-orgs filtering,
+   * external-org lookup); when absent, OSS behavior byte-identical.
+   */
+  readonly organizationDirectory?: OrganizationDirectory;
+  /**
+   * The channel delivery runtime (DD-004's serving seam; single-instance
+   * point). When composed, the agentchannel install arms, the whole
+   * messaging and conversation surfaces, and the two write/delete hooks
+   * delegate to it; with none, the byte-pinned refusal posture serves
+   * (src/domain/agentchannel/channel-runtime.ts carries the contract).
+   */
+  readonly channelRuntime?: ChannelRuntime;
+  /**
+   * The list read scope (20260830.01; single-instance point; absorbs C2
+   * Stage 4's ExecutionReadScope). When composed, every ruled list-shaped
+   * read — the census of docs/authorization-coverage.md — narrows to the
+   * caller's authorized rows: post-scan lanes through
+   * restrictListByReadScope, the search/activity/summary lanes through
+   * the enumeration verb. When absent, the OSS full scan — byte-identical.
+   */
+  readonly listReadScope?: ListReadScope;
+  /**
+   * The visitor error policy (20260830.03; single-instance point) — the
+   * edition semantics of the serving chain's error boundary: WHO is on
+   * the anonymous surface and WHAT copy replaces a leak-prone
+   * description. When absent, the boundary runs only its structural
+   * raw-error conversion — OSS wire behavior otherwise byte-identical.
+   */
+  readonly visitorErrorPolicy?: VisitorErrorPolicy;
+  /**
+   * Secret codecs registrable by wire-format version token (20260830.04
+   * Stage 1, gate ruling Q2) — one entry per enc:v<N>: format the
+   * composition can read and (when selected by
+   * STIGMER_ENCRYPTION_WRITE_VERSION) write. Instances, not factories:
+   * the Java posture is "registration IS the ability to encrypt" — a
+   * codec exists exactly when its key machinery does. The built-in "v1"
+   * token is reserved (the OSS static-key codec installs at the
+   * compose.ts consumption site); registering it, or duplicating a
+   * version across units, is a boot throw. When absent, the facade is
+   * v1-only — OSS behavior byte-identical.
+   */
+  readonly secretCodecs?: ReadonlyMap<string, SecretCodec>;
+  /**
+   * The schedule-fire caller mint (stigmer-cloud#572; single-instance
+   * point) — the identity a schedule fire acts as when it re-enters the
+   * execution create pipeline. When composed, the RunStarter propagates
+   * the minted caller through the R5 in-process header on every fire
+   * (cron tick and manual trigger alike); when absent, fires enter as
+   * the `internal` class — OSS behavior byte-identical.
+   */
+  readonly scheduleFireCaller?: ScheduleFireCallerMint;
+}