@stigmer/server 3.16.0 → 3.17.0

package/src/domain/platform/controller.ts

@@ -1,13 +1,20 @@
 /**
  * Platform controller — ports pkg/domain/platform: the server's
  * self-description surface (NOT a resource domain — no store, no
- * pipelines; three direct handlers on PlatformQueryController).
+ * pipelines; four direct handlers on PlatformQueryController).
  *
- * Proven by platform.conformance.test.ts (getServerInfo +
- * getRunnerBootstrapConfig shapes; getRunnerScopedToken is deliberately
- * excluded there — its arms are exercised mid-execution) and
- * __tests__/platform.test.ts (the fail-soft mint matrix, the #15
- * composed-server pattern).
+ * Proven by platform.conformance.test.ts (getServerInfo,
+ * getRunnerBootstrapConfig and getLicenseStatus shapes; getRunnerScopedToken
+ * is deliberately excluded there — its arms are exercised mid-execution)
+ * and __tests__/platform.test.ts (the fail-soft mint matrix, the license
+ * status arms, the #15 composed-server pattern).
+ *
+ * getLicenseStatus is the one arm every edition answers from a driver
+ * point: a server's license is a fact about the server, like its edition,
+ * and the provider behind `deps.licenseStatus` is the one place that
+ * knows it (extensions/license-status.ts). The controller owns the clock
+ * — it hands the provider one instant and stamps checked_at from the same
+ * one — and copies the provider's presence contract to the wire unchanged.
  *
  * getRunnerScopedToken is the mint side of the runner-token lane
  * (oss#535) — the seam src/runnerauth/. What the token IS depends on the
@@ -41,8 +48,11 @@
  */
 import type { ConnectRouter, HandlerContext } from "@connectrpc/connect";
 import { create } from "@bufbuild/protobuf";
+import { timestampFromDate } from "@bufbuild/protobuf/wkt";
 
+import { LicenseState } from "@stigmer/protos/ai/stigmer/platform/v1/license_pb";
 import {
+  GetLicenseStatusOutputSchema,
   GetRunnerBootstrapConfigOutputSchema,
   GetRunnerScopedTokenOutputSchema,
   GetServerInfoOutputSchema,
@@ -50,6 +60,7 @@ import {
   ServerEdition,
 } from "@stigmer/protos/ai/stigmer/platform/v1/server_info_pb";
 import type {
+  GetLicenseStatusOutput,
   GetRunnerBootstrapConfigOutput,
   GetRunnerScopedTokenInput,
   GetRunnerScopedTokenOutput,
@@ -57,6 +68,7 @@ import type {
 } from "@stigmer/protos/ai/stigmer/platform/v1/server_info_pb";
 
 import type { Logger } from "../../boot/logger.js";
+import type { LicenseStatusProvider } from "../../extensions/license-status.js";
 import { callerIdentityOf } from "../../pipeline/interceptors/auth.js";
 import type {
   RunnerCredentialProvider,
@@ -88,6 +100,18 @@ export interface PlatformControllerDeps {
    * cloud composition answers `cloud` without forking this controller.
    */
   readonly edition: ServerEdition;
+  /**
+   * What license this server holds (extensions/license-status.ts). The
+   * composition root installs the built-in `absent` provider when no unit
+   * registers one, so the field is required: a server that cannot answer
+   * the question is a wiring error, never a silent no-op.
+   */
+  readonly licenseStatus: LicenseStatusProvider;
+  /**
+   * The clock getLicenseStatus evaluates against — injected so a test can
+   * pin that the provider's instant and checked_at are the same one.
+   */
+  readonly now: () => Date;
   readonly logger: Logger;
 }
 
@@ -98,6 +122,7 @@ export function registerPlatformServices(
 ): void {
   router.service(PlatformQueryController, {
     getServerInfo: () => getServerInfo(deps),
+    getLicenseStatus: () => getLicenseStatus(deps),
     getRunnerBootstrapConfig: (_input, ctx) =>
       getRunnerBootstrapConfig(deps, ctx),
     getRunnerScopedToken: (input, ctx) =>
@@ -113,6 +138,51 @@ function getServerInfo(deps: PlatformControllerDeps): GetServerInfoOutput {
   });
 }
 
+/**
+ * The state of the license this server holds, as the composed provider
+ * reports it at one instant.
+ *
+ * The report's arm (extensions/license-status.ts) is copied to the wire
+ * field for field, so the output's presence contract holds by construction:
+ * claims exactly when a ticket verified, key_id whenever one was presented.
+ * checked_at is stamped from the SAME instant the provider evaluated
+ * against, so the answer can never say "valid as of now" about a moment
+ * other than the one it was asked about. No caller check beyond
+ * authentication: the annotation is is_skip_authorization because the
+ * banner this feeds is for every signed-in person, and the handler adds
+ * none (the RPC comment states it).
+ */
+async function getLicenseStatus(
+  deps: PlatformControllerDeps,
+): Promise<GetLicenseStatusOutput> {
+  const now = deps.now();
+  const report = await deps.licenseStatus.status(now);
+  const output = create(GetLicenseStatusOutputSchema, {
+    state: report.state,
+    checkedAt: timestampFromDate(now),
+  });
+  switch (report.state) {
+    case LicenseState.absent:
+      return output;
+    case LicenseState.invalid:
+      output.keyId = report.keyId;
+      return output;
+    case LicenseState.valid:
+    case LicenseState.expiring:
+    case LicenseState.grace:
+    case LicenseState.expired:
+      output.keyId = report.keyId;
+      output.claims = report.claims;
+      return output;
+    default: {
+      const exhaustive: never = report;
+      throw new Error(
+        `unhandled license report: ${JSON.stringify(exhaustive)}`,
+      );
+    }
+  }
+}
+
 /**
  * Go GetRunnerBootstrapConfig: the Temporal coordinates an embedded runner
  * should connect to so it can self-bootstrap from a token alone. The

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

@@ -7,7 +7,9 @@
  * agent, the `mcpServers` key-to-slug rule, a skill archive rooted at its
  * SKILL.md with the plugin's labels on the request, a version the tag
  * pattern rejects becoming a warning, an overlay that redefines the
- * transport refused, and the convergence and drop rules over members.
+ * transport refused, the composed agent declaring its tools' variables
+ * (OAuth targets excluded, an authored agent left as written), and the
+ * convergence and drop rules over members.
  */
 import { describe, expect, it } from "vitest";
 
@@ -19,8 +21,11 @@ import type { PluginPackage } from "@stigmer/plugin-package";
 import { cursorPlugin, openPlugin } from "@stigmer/plugin-package/testing";
 import type { PluginFixture } from "@stigmer/plugin-package/testing";
 import { create } from "@bufbuild/protobuf";
+import { AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import { AgentSpecSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
 import { McpServerSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
 import {
+  McpServerAuthSchema,
   McpServerSpecSchema,
   StdioServerConfigSchema,
 } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/spec_pb";
@@ -224,6 +229,60 @@ describe("planMaterialization", () => {
     expect(builtPlan.skills[0]!.request.tag).toBe("");
   });
 
+  it("declares the servers' variables on the composed agent so a session asks for them", () => {
+    expect(plan.agent!.resource.spec?.env).toEqual({
+      GITHUB_TOKEN: expect.objectContaining({ isSecret: true, optional: false }),
+    });
+  });
+
+  it("leaves an OAuth-managed target out of the agent's declarations", () => {
+    const overlay = create(McpServerSchema, {
+      spec: create(McpServerSpecSchema, {
+        auth: create(McpServerAuthSchema, { targetEnvVar: "GITHUB_TOKEN" }),
+      }),
+    });
+    const withOAuth = planMaterialization(
+      pkg,
+      inMemoryPluginFiles(thermos),
+      {
+        workflows: [],
+        mcpServers: [
+          {
+            path: "ai.stigmer/mcp-servers/my_github.yaml",
+            server: "my_github",
+            resource: overlay,
+          },
+        ],
+      },
+      IDENTITY,
+      "",
+    );
+    // The server still declares it (the connect flow reads it there); the
+    // agent does not, because the value comes from a managed environment.
+    expect(withOAuth.mcpServers[0]!.resource.spec?.env).toHaveProperty("GITHUB_TOKEN");
+    expect(withOAuth.agent!.resource.spec?.env).toEqual({});
+  });
+
+  it("takes an authored agent as written, declarations included", () => {
+    const authored = create(AgentSchema, {
+      spec: create(AgentSpecSchema, {
+        instructions: "The author's own instructions for this agent.",
+      }),
+    });
+    const withOverlay = planMaterialization(
+      pkg,
+      inMemoryPluginFiles(thermos),
+      {
+        agent: { path: "ai.stigmer/agent.yaml", resource: authored },
+        workflows: [],
+        mcpServers: [],
+      },
+      IDENTITY,
+      "",
+    );
+    expect(withOverlay.agent!.resource.spec?.env).toEqual({});
+  });
+
   it("refuses a server overlay that redefines the transport", () => {
     const overlay = create(McpServerSchema, {
       spec: create(McpServerSpecSchema, {

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

@@ -296,6 +296,12 @@ describe("Plugin push — materialisation", () => {
       isSecret: true,
       optional: false,
     });
+    // The agent declares the same variable, which is what makes a session
+    // ask for it and the execution's least-privilege filter pass it.
+    expect(agent.spec?.env["GITHUB_TOKEN"]).toMatchObject({
+      isSecret: true,
+      optional: false,
+    });
   });
 
   it("installs an MCP-only plugin as its servers and no agent", async () => {

package/src/domain/plugin/materialize/agent.ts

@@ -14,6 +14,18 @@
  * `mcp_server_usage`, every `agents/*.md` as a `sub_agent` with access to
  * all the plugin's servers and the skills it asked for.
  *
+ * The composed agent declares in `env` the union of its servers' variables,
+ * OAuth-managed target variables excluded. An execution filters its
+ * environment to the AGENT's declared keys, and every client's session
+ * start asks the user for the AGENT's declared keys, so an agent declaring
+ * nothing over a server declaring `${API_TOKEN}` is never asked for the
+ * token and fails at its first tool call. The declaration on the agent is
+ * what routes the user's values to the execution; the declaration on the
+ * server stays too (the connect flow and the runner's per-server filter
+ * read it there). An OAuth target is excluded because its value is injected
+ * from a managed environment, never asked of the user. An author's
+ * `agent.yaml` is taken as written: they chose what to declare.
+ *
  * Model hints are recorded, never applied: a dialect's `model` becomes a
  * status warning and the sub-agent runs on the session's model. The
  * catalog seam exposes neither family nor cost tier, the runner drops a
@@ -25,6 +37,7 @@
 import { create } from "@bufbuild/protobuf";
 
 import type { PluginPackage, PluginSubAgent } from "@stigmer/plugin-package";
+import type { EnvVarDeclaration } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/spec_pb";
 import { AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
 import type { Agent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
 import {
@@ -47,6 +60,7 @@ import { renderDefaultAgentInstructions } from "./default-agent-instructions.js"
 import { memberMetadata } from "./identity.js";
 import type { PluginIdentity } from "./identity.js";
 import { mcpServerSlugOf } from "./mcp-servers.js";
+import type { PlannedMcpServer } from "./mcp-servers.js";
 import { skillSlugOf } from "./skills.js";
 
 export interface PlannedAgent {
@@ -67,6 +81,7 @@ export function carriesAgent(plugin: PluginPackage): boolean {
 export function planAgent(
   plugin: PluginPackage,
   overlayAgent: Agent | undefined,
+  mcpServers: readonly PlannedMcpServer[],
   identity: PluginIdentity,
   warnings: PluginWarning[],
 ): PlannedAgent | undefined {
@@ -95,6 +110,7 @@ export function planAgent(
   const spec = create(AgentSpecSchema, {
     description: plugin.description ?? "",
     instructions: renderDefaultAgentInstructions(plugin),
+    env: toolVariables(mcpServers),
     skillRefs: [...skillSlugByName.values()].map((slug) =>
       create(ApiResourceReferenceSchema, {
         org: identity.org,
@@ -127,6 +143,28 @@ export function planAgent(
   };
 }
 
+/**
+ * The variables the agent's tools need from the user: every server's
+ * declarations, minus each server's OAuth target. Two servers declaring
+ * one name share one declaration; the first server's wins, and the
+ * library already refuses a plugin whose variables disagree about a name.
+ */
+export function toolVariables(
+  mcpServers: readonly PlannedMcpServer[],
+): Record<string, EnvVarDeclaration> {
+  const declarations: Record<string, EnvVarDeclaration> = {};
+  for (const server of mcpServers) {
+    const spec = server.resource.spec;
+    if (spec === undefined) continue;
+    const oauthTarget = spec.auth?.targetEnvVar ?? "";
+    for (const [name, declaration] of Object.entries(spec.env)) {
+      if (name === oauthTarget || name in declarations) continue;
+      declarations[name] = declaration;
+    }
+  }
+  return declarations;
+}
+
 function planSubAgent(
   subAgent: PluginSubAgent,
   identity: PluginIdentity,

package/src/domain/plugin/materialize/plan.ts

@@ -96,7 +96,13 @@ export function planMaterialization(
     ),
     identity,
   );
-  const agent = planAgent(plugin, overlays.agent?.resource, identity, warnings);
+  const agent = planAgent(
+    plugin,
+    overlays.agent?.resource,
+    mcpServers,
+    identity,
+    warnings,
+  );
   const workflows = planWorkflows(overlays.workflows, identity);
 
   const members: PlannedMember[] = [

package/src/domain/project/__tests__/reconcile.test.ts

@@ -237,10 +237,12 @@ describe("orphan deletion (Go service_test.go)", () => {
     ]);
   });
 
-  it("orphan lookup is slug-only, matching across orgs (pinned Go behavior)", async () => {
-    // Seeded under org "local"; the orphan reference carries a DIFFERENT
-    // org — resolution still matches, because Go's resolveResourceID
-    // filters by slug alone (reconcile/service.go:126).
+  it("orphan lookup is scoped to the reference's org: another org's same-slug resource is never touched", async () => {
+    // Slugs are org-scoped identifiers. Seeded under org "local"; the orphan
+    // reference names a DIFFERENT org, so it must not resolve to this row.
+    // (The Go port matched by slug alone; on a backend with a system org
+    // beside the user's, a prune could then delete the wrong org's
+    // resource — stigmer/stigmer#1151.)
     await seedAgent("agent-id-x", "cross-org-agent");
     const deleter = new RecordingDeleter();
     const previous = [
@@ -251,9 +253,53 @@ describe("orphan deletion (Go service_test.go)", () => {
       }),
     ];
     const result = await service(deleter).reconcile(previous, [], DEFAULT_RECONCILIATION_OPTIONS);
+    expect(result.removed).toHaveLength(0);
+    expect(result.errors).toHaveLength(1);
+    expect(result.errors[0]?.resourceKey).toBe("agent:cross-org-agent");
+    expect(result.errors[0]?.message).toBe("failed to resolve resource for deletion");
+    expect(deleter.calls).toHaveLength(0);
+  });
+
+  it("orphan lookup picks the reference's org when two orgs hold the slug", async () => {
+    await seedAgent("agent-id-local", "shared-slug");
+    await store.saveResource(
+      ApiResourceKind.agent,
+      "agent-id-other",
+      AgentSchema,
+      create(AgentSchema, {
+        apiVersion: "agentic.stigmer.ai/v1",
+        kind: "Agent",
+        metadata: { id: "agent-id-other", name: "shared-slug", slug: "shared-slug", org: "another-org" },
+      }),
+    );
+    const deleter = new RecordingDeleter();
+    const previous = [
+      create(ApiResourceReferenceSchema, {
+        org: "another-org",
+        kind: ApiResourceKind.agent,
+        slug: "shared-slug",
+      }),
+    ];
+    const result = await service(deleter).reconcile(previous, [], DEFAULT_RECONCILIATION_OPTIONS);
+    expect(result.removed).toHaveLength(1);
+    expect(deleter.calls).toEqual([
+      { kind: ApiResourceKind.agent, resourceId: "agent-id-other" },
+    ]);
+  });
+
+  it("a reference without an org keeps the unscoped lookup (a pre-scoping client's project)", async () => {
+    await seedAgent("agent-id-y", "legacy-agent");
+    const deleter = new RecordingDeleter();
+    const previous = [
+      create(ApiResourceReferenceSchema, {
+        kind: ApiResourceKind.agent,
+        slug: "legacy-agent",
+      }),
+    ];
+    const result = await service(deleter).reconcile(previous, [], DEFAULT_RECONCILIATION_OPTIONS);
     expect(result.removed).toHaveLength(1);
     expect(deleter.calls).toEqual([
-      { kind: ApiResourceKind.agent, resourceId: "agent-id-x" },
+      { kind: ApiResourceKind.agent, resourceId: "agent-id-y" },
     ]);
   });
 

package/src/domain/project/reconcile.ts

@@ -37,6 +37,7 @@ import { ReconciliationSummarySchema } from "@stigmer/protos/ai/stigmer/tenancy/
 import type { ReconciliationSummary } from "@stigmer/protos/ai/stigmer/tenancy/project/v1/status_pb";
 
 import type { Logger } from "../../boot/logger.js";
+import { findResourceBySlug } from "../../pipeline/steps/helpers.js";
 import { metadataOf } from "../../pipeline/steps/shapes.js";
 import type { Store } from "../../store/interface.js";
 
@@ -205,28 +206,32 @@ async function deleteOrphans(
 }
 
 /**
- * Resolves an orphan reference to its resource id — Go resolveResourceID:
- * FindByField on metadata.slug, SLUG ONLY, no org filter (the pinned
- * behavior: first match of that kind+slug across all orgs; tolerable in
- * single-tenant OSS).
+ * Resolves an orphan reference to its resource id, within the org the
+ * reference names. Slugs are org-scoped identifiers: a local backend holds
+ * the `stigmer` system org beside the user's, a self-host holds many, and
+ * the same slug may exist in several. The Go port matched by slug alone and
+ * could prune another org's resource (stigmer/stigmer#1151); the CLI has
+ * always stamped `org` on every member reference, so scoping is a change
+ * of lookup, not of contract. A reference without an org (a project written
+ * before members carried one) keeps the unscoped match, the helper's
+ * documented empty-org arm.
  */
 async function resolveResourceId(
   store: Store,
   ref: ApiResourceReference,
 ): Promise<string> {
   const schema = schemaForKind(ref.kind);
-  let resource;
-  try {
-    resource = await store.findByField(
-      ref.kind,
-      "metadata.slug",
-      ref.slug,
-      schema,
-    );
-  } catch (cause) {
+  const resource = await findResourceBySlug(
+    store,
+    ref.kind,
+    schema,
+    ref.slug,
+    ref.org,
+  );
+  if (resource === undefined) {
+    const where = ref.org === "" ? "" : ` in org '${ref.org}'`;
     throw new Error(
-      `resource ${kindName(ref.kind)}/${ref.slug} not found: ${cause instanceof Error ? cause.message : String(cause)}`,
-      { cause },
+      `resource ${kindName(ref.kind)}/${ref.slug} not found${where}`,
     );
   }
 

package/src/domain/workflow/registry/data/task-kind-registry.json

@@ -1518,7 +1518,10 @@
                     "schedule",
                     "memory",
                     "plugin",
-                    "project"
+                    "project",
+                    "plan",
+                    "subscription",
+                    "license"
                   ],
                   "type": "string"
                 },

package/src/extensions/__tests__/license-status-points.test.ts

@@ -0,0 +1,50 @@
+/**
+ * Pins the licenseStatus driver point in the single-instance shape the
+ * registry already enforces for organizationDirectory and identityFederation:
+ *
+ *   - `drivers.licenseStatus` — the provider that answers what license this
+ *     server holds (an Enterprise unit registers the one that verifies a
+ *     configured ticket); single instance; absent = the built-in `absent`
+ *     provider installs at the compose.ts consumption site, so every
+ *     edition answers getLicenseStatus and only one ever answers anything
+ *     but absent.
+ *
+ * The controller's use of the resolved provider is pinned in
+ * domain/platform/__tests__/platform.test.ts; this file pins the registry.
+ */
+import { LicenseState } from "@stigmer/protos/ai/stigmer/platform/v1/license_pb";
+import { describe, expect, it } from "vitest";
+
+import type { LicenseStatusProvider } from "../license-status.js";
+import { resolveExtensions } from "../registry.js";
+
+// An invalid report is the smallest complete one a provider can give: the
+// registry test needs an instance to carry through, not a verified ticket.
+const provider: LicenseStatusProvider = {
+  status: () =>
+    Promise.resolve({ state: LicenseState.invalid, keyId: "lk_test" }),
+};
+
+describe("the licenseStatus driver point", () => {
+  it("is undefined with no extensions — the built-in absent provider serves", () => {
+    expect(resolveExtensions([]).drivers.licenseStatus).toBeUndefined();
+  });
+
+  it("carries the one registered instance through", () => {
+    const resolved = resolveExtensions([
+      { name: "enterprise-license", drivers: { licenseStatus: provider } },
+    ]);
+    expect(resolved.drivers.licenseStatus).toBe(provider);
+  });
+
+  it("throws on a second registration, naming both units", () => {
+    expect(() =>
+      resolveExtensions([
+        { name: "license-a", drivers: { licenseStatus: provider } },
+        { name: "license-b", drivers: { licenseStatus: provider } },
+      ]),
+    ).toThrowError(
+      /extension 'license-b' registers a LicenseStatusProvider, but 'license-a' already did/,
+    );
+  });
+});

package/src/extensions/drivers.ts

@@ -53,6 +53,7 @@ import type { RunnerCredentialProvider } from "../runnerauth/runner-credential-p
 import type { SandboxProvisionerFactory } from "../sandbox/provisioner.js";
 import type { AuthorizationQueryEngine } from "./authorization-queries.js";
 import type { IdentityFederation } from "./identity-federation.js";
+import type { LicenseStatusProvider } from "./license-status.js";
 import type { ListReadScope } from "./list-read-scope.js";
 import type { OrganizationDirectory } from "./organization-directory.js";
 import type { PolicyGrantScope } from "./policy-grant-scope.js";
@@ -219,4 +220,14 @@ export interface ExtensionDrivers {
    * with the edition reason — the identityFederation absent shape.
    */
   readonly authorizationQueries?: AuthorizationQueryEngine;
+  /**
+   * The license-status provider (single-instance point): what license
+   * this server holds, answered by PlatformQueryController.getLicenseStatus
+   * in every edition. An Enterprise unit registers the provider that
+   * verifies its configured ticket; when absent, the built-in `absent`
+   * answer installs at the compose.ts consumption site, so open source
+   * and the cloud (which hold no key) answer the same question the same
+   * way (extensions/license-status.ts carries the contract).
+   */
+  readonly licenseStatus?: LicenseStatusProvider;
 }

package/src/extensions/license-status.ts

@@ -0,0 +1,71 @@
+/**
+ * The license-status extension point: what license does this server hold?
+ *
+ * Every edition answers the question through
+ * PlatformQueryController.getLicenseStatus, because a server's license is a
+ * fact about the server, like its edition, and the console banner that
+ * reads it ("licensed to Acme until March") must work wherever it is shown.
+ * Only one edition ever has a license to report: the Enterprise composition
+ * registers the provider that verifies the ticket it was configured with.
+ * Open source and the cloud hold no key, so with no provider composed the
+ * built-in `absent` answer below installs at the boot/compose.ts
+ * consumption site (the default-lives-with-the-consumer doctrine; see
+ * drivers.ts).
+ *
+ * The port speaks the generated claim types rather than a domain twin. The
+ * claims ARE the wire — the ticket's payload is the proto JSON of
+ * LicenseClaims — so a hand-written copy would be exactly the duplicate of a
+ * generated type the SDK and server guides forbid.
+ *
+ * The controller owns the clock: it hands the provider ONE instant and
+ * stamps the answer's checked_at from the same one, so a report and its
+ * timestamp can never disagree about when the license was evaluated. A
+ * provider therefore takes `now` and never reads the wall clock itself.
+ *
+ * The report is a union keyed on the state, not a bag of optional fields,
+ * so the wire's presence contract (GetLicenseStatusOutput) is a fact the
+ * compiler holds rather than a sentence a provider has to remember: an
+ * `invalid` report cannot carry the claims that did not verify, a `valid`
+ * one cannot omit them, and `unspecified` cannot be reported at all.
+ */
+import type { LicenseClaims } from "@stigmer/protos/ai/stigmer/platform/v1/license_pb";
+import { LicenseState } from "@stigmer/protos/ai/stigmer/platform/v1/license_pb";
+
+/**
+ * The states in which a ticket's signature verified and its claims are
+ * trusted; what separates them is only where the clock stands in the term.
+ */
+export type VerifiedLicenseState =
+  | LicenseState.valid
+  | LicenseState.expiring
+  | LicenseState.grace
+  | LicenseState.expired;
+
+/**
+ * A provider's answer, evaluated at the instant it was given. One arm per
+ * presence shape: no ticket configured; a ticket that named a key and did
+ * not verify; a ticket that verified, with the key it named and the claims
+ * it carried. The controller copies the arm to the wire field for field.
+ */
+export type LicenseStatusReport =
+  | { readonly state: LicenseState.absent }
+  | { readonly state: LicenseState.invalid; readonly keyId: string }
+  | {
+      readonly state: VerifiedLicenseState;
+      readonly keyId: string;
+      readonly claims: LicenseClaims;
+    };
+
+/** The provider contract (single-instance point, ExtensionDrivers.licenseStatus). */
+export interface LicenseStatusProvider {
+  /** The license's state as of `now`, the instant the answer is stamped with. */
+  status(now: Date): Promise<LicenseStatusReport>;
+}
+
+/**
+ * The built-in answer for a server that holds no license: open source and
+ * the cloud, and an Enterprise composition that registered no provider.
+ */
+export const ABSENT_LICENSE_STATUS: LicenseStatusProvider = {
+  status: () => Promise.resolve({ state: LicenseState.absent }),
+};

package/src/extensions/registry.ts

@@ -53,6 +53,7 @@ import type { SecretCodec } from "../encryption/codec.js";
 import { V1_VERSION } from "../encryption/v1-codec.js";
 import type { AuthorizationQueryEngine } from "./authorization-queries.js";
 import type { IdentityFederation } from "./identity-federation.js";
+import type { LicenseStatusProvider } from "./license-status.js";
 import type { ListReadScope } from "./list-read-scope.js";
 import type { PolicyGrantScope } from "./policy-grant-scope.js";
 import type { ModelCatalogProvider } from "../domain/workflow/registry/model-catalog-provider.js";
@@ -272,6 +273,11 @@ export interface ResolvedExtensionDrivers {
    * tuple-half RPC arms refuse UNIMPLEMENTED with the edition reason.
    */
   readonly authorizationQueries: AuthorizationQueryEngine | undefined;
+  /**
+   * The license-status provider — undefined = compose.ts installs the
+   * built-in `absent` answer, so every edition serves getLicenseStatus.
+   */
+  readonly licenseStatus: LicenseStatusProvider | undefined;
 }
 
 /**
@@ -325,6 +331,8 @@ export function resolveExtensions(
   let policyGrantScopeDeclaredBy: string | undefined;
   let authorizationQueries: AuthorizationQueryEngine | undefined;
   let authorizationQueriesDeclaredBy: string | undefined;
+  let licenseStatus: LicenseStatusProvider | undefined;
+  let licenseStatusDeclaredBy: string | undefined;
   const artifactStorageDrivers = new Map<
     string,
     ArtifactStorageDriverFactory
@@ -516,6 +524,16 @@ export function resolveExtensions(
       authorizationQueriesDeclaredBy = unit.name;
     }
 
+    if (unit.drivers?.licenseStatus !== undefined) {
+      if (licenseStatusDeclaredBy !== undefined) {
+        throw new Error(
+          `extension '${unit.name}' registers a LicenseStatusProvider, but '${licenseStatusDeclaredBy}' already did — exactly one may be composed`,
+        );
+      }
+      licenseStatus = unit.drivers.licenseStatus;
+      licenseStatusDeclaredBy = unit.name;
+    }
+
     if (unit.drivers?.artifactStorageDrivers !== undefined) {
       for (const [name, factory] of unit.drivers.artifactStorageDrivers) {
         if ((BUILT_IN_STORAGE_TYPES as ReadonlyArray<string>).includes(name)) {
@@ -641,6 +659,7 @@ export function resolveExtensions(
       iamPolicyStore,
       policyGrantScope,
       authorizationQueries,
+      licenseStatus,
     },
     services,
     workers,