@stigmer/server 3.14.0-dev.20260910084630

package/src/index.ts

@@ -0,0 +1,351 @@
+/**
+ * The @stigmer/server library contract (DD-005, sub-project 20260826.09).
+ *
+ * This file IS the blessed surface: the package.json exports map resolves
+ * the bare package name here and nowhere else, so everything a consumer
+ * (the cloud composition, or any composition built on the published
+ * package) may import appears below — and nothing else does. Deep imports
+ * into dist/ internals are unsupported; anything a consumer needs that is
+ * not exported is a seam request to OSS, never a reach-around. Additions
+ * to this file are owner-visible surface changes, extended only through
+ * gates (the DD-005 review property: a surface change is a one-file diff).
+ *
+ * The surface is exactly what the ratified architecture names (blueprint
+ * 20260826.02/03 §1) and the parameter types those entries force:
+ *   - the compose entry and config loading (composeServer + its options'
+ *     required types: ServerConfig via loadConfig, Logger via createLogger)
+ *   - the extension-point types (§2 — the whole src/extensions contract)
+ *   - the pipeline primitives extensions build gates AND extension-
+ *     registered services from (PipelineStep, RequestContext, the semantic
+ *     error helpers, and the typed store not-found errors the ratified
+ *     store-fault mapping keys on; C4 Stage 3 added the dispatch-policy
+ *     configs and the loaded-execution context key its capacity gates
+ *     consume; C4 Stage 4 added the executor, the identity read idiom,
+ *     and the two chain-front steps so extension services run the SAME
+ *     request idiom OSS controllers run)
+ *   - the driver interfaces (Store, ArtifactStorage; O5 added §6a/§6b/§6c —
+ *     ModelCatalogProvider, the widened storage surface, and
+ *     RunnerCredentialProvider; O6 added §6d — SandboxProvisioner and its
+ *     factory/registration types)
+ *   - the worker factory types extension workers implement (§8)
+ *   - the Postgres driver constructor (20260910.04 ruling 4), for a
+ *     composition that shares ONE database with this chain
+ *
+ * The package publishes to npm in lockstep with every other @stigmer/*
+ * package (stigmer-cloud project 20260910.04, amending DD-005): this file
+ * is the versioned contract a consumer pins by exact version. Everything
+ * below the barrel is internal and may change between releases without
+ * notice; everything on it changes only through a gate. The same server
+ * also ships as @stigmer/server-slim — the bundled deployable `stigmer up`
+ * launches — which exports nothing and is not a library.
+ */
+
+// The compose entry and config loading.
+export { composeServer } from "./boot/compose.js";
+export type { ComposeOptions, ComposedServer } from "./boot/compose.js";
+export { loadConfig } from "./boot/config.js";
+export type { ServerConfig } from "./boot/config.js";
+export { createLogger } from "./boot/logger.js";
+export type {
+  LogEntry,
+  LogFields,
+  Logger,
+  LoggerOptions,
+  LogLevel,
+  LogSink,
+} from "./boot/logger.js";
+
+// The extension-point types (DD-006 — the seven-point registry).
+export type {
+  ExtensionServiceRegistration,
+  ResolvedExtensions,
+  ServerExtension,
+} from "./extensions/registry.js";
+export type {
+  CallerClass,
+  CallerIdentity,
+  IdentityVerifier,
+} from "./extensions/identity.js";
+// The 20260902.02 seam: post-authentication caller guards
+// (ServerExtension.callerGuards) — enforcement of the MINTING CLIENT's
+// contract, run by the serving chassis after the position-1 identity
+// stamp and never by the in-process chain (the structural exemption).
+// The composition owns WHO is exempt and WHAT refuses (skip sets,
+// byte-pinned copy, liveness reads); OSS owns the walk, the fault
+// mapping (ConnectError = the guard's wire shape; any other throw =
+// INTERNAL), and the ordering.
+export type { CallerGuard } from "./extensions/caller-guards.js";
+// The caller-identity read idiom for extension-registered services (C2
+// Stage 3, 20260827.10): extension RPC handlers traverse the same
+// interceptor chain as OSS controllers, so the identity stamped at chain
+// position 1 is already on the HandlerContext — the exported accessor
+// below (with the R5 propagation surface) is the ONE sanctioned way to
+// read it.
+export type {
+  Authorizer,
+  AuthzCheck,
+  AuthzDecision,
+} from "./extensions/authorizer.js";
+export type { GateSlotName } from "./extensions/gate-slots.js";
+export type {
+  AgentExecutionResponseDecorator,
+  AgentExecutionStatusHooks,
+  AgentExecutionStatusObserver,
+  AgentExecutionStatusTransition,
+} from "./extensions/status-hooks.js";
+export type { ExtensionDrivers } from "./extensions/drivers.js";
+export type { ResolvedExtensionDrivers } from "./extensions/registry.js";
+// The C2 seams (20260827.10): the tuple-lifecycle driver point and the
+// organization query directory, plus the shape-policy helpers a driver's
+// tests pin against.
+export type {
+  DefaultInstanceLinkedEvent,
+  ResourceAuthorizationLifecycle,
+  ResourceCreatedEvent,
+  ResourceDeletedEvent,
+  VisibilityChangedEvent,
+  VisibilityTupleShape,
+  ResolvedParentLink,
+} from "./extensions/resource-authorization.js";
+export type { OrganizationDirectory } from "./extensions/organization-directory.js";
+export { ALL_ORGANIZATIONS } from "./extensions/organization-directory.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.
+export type { ScheduleFireCallerMint } 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
+// replaces a leak-prone description; the boundary owns the mechanism
+// (code set, code preservation, ref format, details-drop). The factory
+// rides the callerIdentityKey precedent: production wiring stays
+// compose.ts's job, but a composition's OWN tests must drive its policy
+// through the REAL boundary mechanism, never a re-derivation.
+export type { VisitorErrorPolicy } from "./pipeline/interceptors/error-boundary.js";
+export { createErrorBoundaryInterceptor } from "./pipeline/interceptors/error-boundary.js";
+export {
+  diffVisibilityShapes,
+  visibilityShapesFor,
+} from "./pipeline/steps/authorization-tuples.js";
+
+// The pipeline primitives extensions build gate steps from.
+export type { PipelineStep } from "./pipeline/pipeline.js";
+export { RequestContext } from "./pipeline/request-context.js";
+export {
+  abortedError,
+  alreadyExistsError,
+  failedPreconditionError,
+  internalError,
+  invalidArgumentError,
+  notFoundError,
+  unavailableError,
+} from "./pipeline/errors.js";
+// The shared slug derivation (C2 Stage 3): extension-registered resource
+// kinds derive slugs with the SAME generator both editions pin
+// (ApiRequestResourceSlugGenerator parity) — the semantics live exactly
+// once.
+export { generateSlug } from "./pipeline/steps/slug.js";
+// The in-process caller-propagation surface (ruling R5): extension code
+// composing requests through the in-process transport AS a caller rides
+// the same header the OSS asCaller adapters use. (callerIdentityOf and
+// callerIdentityKey ride the request-idiom export block below.)
+export {
+  encodeInProcessCaller,
+  IN_PROCESS_CALLER_HEADER,
+} from "./pipeline/interceptors/auth.js";
+
+// The request idiom for extension-REGISTERED services (C4 Stage 4): a
+// service contributed through ServerExtension.services runs the same
+// chain shape every OSS controller runs — identity read once
+// (callerIdentityOf), then Authorize (descriptor-driven from the
+// `(ai.stigmer.commons.rpc.config)` method options, owning the ratified
+// three-arm decision mapping and the `internal`-caller skip) and
+// ValidateProto at the chain front, executed by the pipeline (which owns
+// the sanitized-Internal error contract). Blessing these keeps
+// authorization and validation semantics single-definition: an extension
+// hand-rolling either would re-derive ratified wire behavior.
+// callerIdentityKey is the stamp side of the same contract — production
+// stamping stays the interceptors' job, but an extension's OWN service
+// tests must stamp what the serving chain stamps (the auth.test.ts
+// idiom) to exercise their chains over a router transport.
+export {
+  callerIdentityKey,
+  callerIdentityOf,
+} from "./pipeline/interceptors/auth.js";
+// The serving chassis factory (20260902.02, the error-boundary
+// precedent): a composition's OWN tests must drive its caller guards
+// through the REAL stamp→guard mechanism — the walk order, the fault
+// mapping, the refusal pass-through — never a re-derivation. Production
+// wiring stays compose.ts's job.
+export { createVerifierChainInterceptor } from "./pipeline/interceptors/auth.js";
+// The interceptor's inner identity walk on its own (stigmer#991): a
+// composition's extension-owned HTTP lanes are not Connect requests and
+// cannot ride the interceptor, but they must authenticate a presented
+// bearer with the SAME composed chain — one walk, two edges, never a
+// re-instantiated verifier list. Identity only; caller guards stay the
+// serving interceptor's (RPC-shaped by contract).
+export {
+  authenticateBearerToken,
+  parseBearerToken,
+} from "./pipeline/interceptors/auth.js";
+export { newPipeline } from "./pipeline/pipeline.js";
+export { newAuthorizeStep } from "./pipeline/steps/authorize.js";
+export { newValidateProtoStep } from "./pipeline/steps/validation.js";
+
+// The driver interfaces and the store-fault classes the ratified mapping
+// keys on (typed not-found → NotFound; anything else rethrows as an
+// infrastructure fault — the guidelines' instanceof idiom).
+export type { Store } from "./store/interface.js";
+export {
+  AuditNotFoundError,
+  ResourceNotFoundError,
+} from "./store/interface.js";
+// The maintenance-surface row shape (20260830.04 Stage 1, ruling Q3):
+// what findResourcesRawOrderedAfter pages and what
+// replaceResourceDataIfUnchanged guards on — the secret-convergence
+// sweep's storage contract.
+export type { RawResourceDocument } from "./store/interface.js";
+// The Postgres driver constructor (stigmer-cloud 20260910.04 ruling 4;
+// the newR2ArtifactStorage precedent for blessing a driver constructor).
+// A composition that runs its own schema chain in the SAME database as
+// this chain needs the OSS tables provisioned in its DB-backed tests
+// exactly as production provisions them: PostgresStore.open runs the
+// versioned chain under its advisory lock. The migrations themselves stay
+// internal — a consumer gets the driver, never the DDL — so the chain's
+// shape is not a contract and nothing outside this package can replay it
+// piecemeal. Not for production wiring: compose.ts selects the driver from
+// config (DD-010), and a composition never opens a second store.
+export { PostgresStore } from "./store/postgres/store.js";
+export type {
+  ArtifactStorage,
+  ArtifactStorageDriverFactory,
+  PresignedUpload,
+  StagedUploadLane,
+} from "./artifactstorage/artifact-storage.js";
+export { ArtifactStorageNotFoundError } from "./artifactstorage/artifact-storage.js";
+// The R2 driver constructor (C1 seam, 20260827.04): compositions register
+// per-domain R2 drivers with their own bucket/credential config while the
+// S3 plumbing lives exactly once in OSS (the §6b registration shape).
+export { newR2ArtifactStorage } from "./artifactstorage/r2-storage.js";
+export type { R2StorageConfig } from "./artifactstorage/r2-storage.js";
+
+// The O5 driver seams (§6a/§6c): the model-catalog read surface with the
+// DD-008 disciplines in its contract, and the per-lane runner-credential
+// seam with its OSS lane constant (an extension's verify callers name the
+// lane they accept).
+export type { ModelCatalogProvider } from "./domain/workflow/registry/model-catalog-provider.js";
+// The document-driven provider constructor (C1 seam, 20260827.04): a
+// composition whose catalog source is its own (the cloud's DB-resident
+// baseline) builds providers from documents with the SAME interpretation
+// ModelRegistryStore uses — the semantics live exactly once in OSS.
+export { newModelCatalogProviderFromDocument } from "./domain/workflow/registry/document-catalog.js";
+export type {
+  RunnerCredentialProvider,
+  // The C4 capability shapes (gate ruling Q1): the optional methods'
+  // domain-shaped request/result types — a composition implementing the
+  // exchange, bootstrap, sandbox-mint, or EC-read capabilities types
+  // against these, never against wire messages.
+  RunnerBootstrapCredentials,
+  RunnerScopedTokenExchange,
+  RunnerScopedTokenRequest,
+  SandboxCredentialRequest,
+  // The parity-entry-20260830.05 capability shape: the memory
+  // capture-eligibility verdict (admit carries the token's proved
+  // subject + session claims for the defaults step's Java-parity
+  // derivation).
+  MemoryCaptureDecision,
+} from "./runnerauth/runner-credential-provider.js";
+export type { MintedToken } from "./runnerauth/runnerauth.js";
+export {
+  InvalidTokenError,
+  MintingDisabledError,
+  TOKEN_TYPE_EXECUTION_SCOPED,
+} from "./runnerauth/runnerauth.js";
+
+// The secret-sealing seam (20260830.04 Stage 1, gate rulings Q2/Q3 —
+// widening the C4-era enc:v1 block): the SecretService facade over the
+// versioned-codec registry (async, scoped, batched, with reencrypt as the
+// sweep's one upgrade door), the SecretCodec contract an extension's
+// vault-backed formats implement (drivers.secretCodecs), the
+// EncryptionScope tenancy/location record every seal site threads, and
+// the TWO-ARMED error taxonomy the skip/propagate policies branch on
+// (value-scoped InvalidCiphertextError family vs infrastructure
+// EncryptionUnavailableError family). The service and its contract types,
+// not the crypto primitives — each wire format stays defined exactly
+// once. The maintenance-surface store verbs this seam blessed ride the
+// Store interface above; RawResourceDocument is their row shape.
+export {
+  DecryptionFailedError,
+  EncryptionDisabledError,
+  EncryptionScope,
+  EncryptionUnavailableError,
+  InvalidCiphertextError,
+  SecretService,
+} from "./encryption/encryption.js";
+export type { SecretCodec } from "./encryption/codec.js";
+
+// The O6 driver seam (§6d): the sandbox-provisioner contract an extension
+// implements to register its own isolation driver (selected through the
+// SANDBOX_PROVISIONER_TYPE knob), plus the reserved built-in names its
+// registrations may never shadow.
+export type {
+  SandboxDriverConfig,
+  SandboxEnvironment,
+  SandboxProbeState,
+  SandboxProvisioner,
+  SandboxProvisionerFactory,
+  SandboxScope,
+} from "./sandbox/provisioner.js";
+export { BUILT_IN_SANDBOX_PROVISIONER_TYPES } from "./sandbox/provisioner.js";
+
+// The C4 Stage 3 gate seams: the dispatch-policy configs a capacity gate
+// reads — the UNSPECIFIED-resolution rules and routing modes are single
+// definitions by doctrine (oss#397), and their own headers name "a future
+// policy consumer" as the reason they must be consumed, never re-derived.
+// Plus the lifecycle chains' loaded-execution context key: recover-chain
+// gate steps read the loaded resource through it (ctx.newState on those
+// chains is the input message, not the resource).
+export {
+  AgentExecutionTemporalConfig,
+  ROUTING_SESSION,
+  newConfigFromEnv as newAgentExecutionTemporalConfigFromEnv,
+} from "./domain/agentexecution/temporal/config.js";
+export {
+  WORKFLOW_ROUTING_EXECUTION,
+  WorkflowExecutionTemporalConfig,
+  newWorkflowExecutionConfigFromEnv,
+} from "./domain/workflowexecution/temporal/config.js";
+export { LOADED_EXECUTION_KEY } from "./pipeline/request-context.js";
+
+// The C3 driver seam (DD-004's serving half, ruling Q1): the channel
+// delivery runtime a composition registers to SERVE the install,
+// messaging, and conversation arms the storing posture refuses — plus
+// the write-constraints and delete-teardown hooks that carry the two
+// edition-split CRUD sites. One driver, grouped by the surfaces it takes
+// over; with none composed the byte-pinned refusals serve unchanged.
+export type {
+  ChannelRuntime,
+  ChannelRuntimeConversations,
+  ChannelRuntimeInstalls,
+  ChannelRuntimeMessaging,
+} from "./domain/agentchannel/channel-runtime.js";
+
+// The worker factory seam extension workers implement (§8). Factories
+// construct workers ONLY through deps.createWorker — this package's
+// @temporalio/worker instance — so a composition never loads a second
+// native bridge for its extension workers (the finding-16 fix; see
+// WorkerFactoryDeps.createWorker in temporal/manager.ts).
+export type {
+  CreateWorkerOptions,
+  WorkerFactory,
+  WorkerFactoryDeps,
+  WorkerWorkflowSource,
+} from "./temporal/manager.js";
+// The SDK's pure-JS workflow bundler, re-exported so factories that
+// prebuild a shared bundle (the channel sweeps' pattern) need no runtime
+// dependency on @temporalio/worker of their own.
+export { bundleWorkflowCode } from "@temporalio/worker";

package/src/main.ts

@@ -0,0 +1,67 @@
+/**
+ * Process entry for stigmer-server. The CLI's daemon launches this the
+ * way it launches the runner: a node binary + bundled entry path, with the
+ * env contract from daemon/env.ts (GRPC_PORT et al.) and a TCP readiness
+ * probe on the bound port.
+ *
+ * SIGTERM/SIGINT run the composed shutdown (NOT_SERVING → drain → exit) —
+ * the daemon stops components with signals, and in-flight requests get the
+ * drain budget rather than a mid-write connection reset.
+ *
+ * The async main() wrapper (not top-level await) is load-bearing: the slim
+ * artifact bundles this entry as CJS (scripts/bundle-slim.mjs), where
+ * top-level await cannot exist.
+ */
+import { loadConfig } from "./boot/config.js";
+import { composeServer } from "./boot/compose.js";
+import { createLogger } from "./boot/logger.js";
+import { setOperatorIdentity } from "./pipeline/steps/defaults.js";
+
+async function main(): Promise<void> {
+  const config = loadConfig();
+  const logger = createLogger({
+    level: config.logLevel,
+    pretty: config.env === "local",
+  });
+  // Once per process, before any writer exists (#400) — the one-shot guard
+  // makes a duplicate install a loud boot bug.
+  setOperatorIdentity(config.operatorEmail, config.operatorName);
+  const server = await composeServer({ config, logger });
+
+  let shuttingDown = false;
+  const shutdown = (signal: string): void => {
+    if (shuttingDown) {
+      return;
+    }
+    shuttingDown = true;
+    logger.info("shutting down", { signal });
+    server
+      .shutdown()
+      .then(() => process.exit(0))
+      .catch((error: unknown) => {
+        logger.error("shutdown failed", { error: String(error) });
+        process.exit(1);
+      });
+  };
+  process.on("SIGTERM", () => shutdown("SIGTERM"));
+  process.on("SIGINT", () => shutdown("SIGINT"));
+
+  try {
+    await server.start();
+  } catch (error) {
+    logger.error("boot failed", {
+      error: error instanceof Error ? error.message : String(error),
+    });
+    process.exit(1);
+  }
+}
+
+main().catch((error: unknown) => {
+  // The logger may not exist yet (config/compose failures) — stderr is the
+  // one channel that always does.
+  console.error(
+    "boot failed:",
+    error instanceof Error ? error.message : String(error),
+  );
+  process.exit(1);
+});

package/src/observability/__tests__/in-memory-meter.ts

@@ -0,0 +1,101 @@
+/**
+ * A REAL OTel MeterProvider backed by an in-memory exporter, for suites
+ * that pin an instrument registry's names, label vocabulary and zero
+ * baselines — what the SigNoz rules key on. The registries are lazy and
+ * memoized on the GLOBAL meter provider (rpc-metrics.ts), so the helper
+ * installs the provider globally and takes the registry's reset seam to
+ * clear the memo before and after; a registry created against an earlier
+ * provider would otherwise keep recording into it.
+ *
+ * Collection is manual (`collect()` forces a flush) and the export interval
+ * is set far out so nothing races the test. Recorders are fire-and-forget
+ * over a dynamic import; callers poll `collect()` with a deadline (`until`)
+ * rather than sleeping — the determinism rule.
+ *
+ * The cloud composition's `src/observability/__tests__/in-memory-meter.ts`
+ * (stigmer-cloud `694b6a57e`) is this file's source; the two registries it
+ * serves there and the one here share the idiom on purpose.
+ */
+
+export interface CollectedPoint {
+  readonly value: unknown;
+  readonly attributes: Record<string, unknown>;
+}
+
+/** Metric name → its data points at the last collection. */
+export type CollectedMetrics = Map<string, CollectedPoint[]>;
+
+export interface InMemoryMeter {
+  /** Flushes the provider and returns every exported metric by name. */
+  collect(): Promise<CollectedMetrics>;
+  /** Shuts the provider down, disables the global API and clears the registry memo. */
+  dispose(): Promise<void>;
+}
+
+/**
+ * @param resetInstruments the registry's test seam (`resetRpcInstruments`),
+ *   invoked after the provider is installed and again on dispose so no
+ *   memoized meter outlives this provider.
+ */
+export async function inMemoryMeter(
+  resetInstruments: () => void,
+): Promise<InMemoryMeter> {
+  const {
+    AggregationTemporality,
+    InMemoryMetricExporter,
+    MeterProvider,
+    PeriodicExportingMetricReader,
+  } = await import("@opentelemetry/sdk-metrics");
+  const api = await import("@opentelemetry/api");
+  const exporter = new InMemoryMetricExporter(
+    AggregationTemporality.CUMULATIVE,
+  );
+  const reader = new PeriodicExportingMetricReader({
+    exporter,
+    // Effectively manual: collection happens on forceFlush in collect().
+    exportIntervalMillis: 3_600_000,
+  });
+  const provider = new MeterProvider({ readers: [reader] });
+  api.metrics.setGlobalMeterProvider(provider);
+  resetInstruments();
+  return {
+    async collect() {
+      await provider.forceFlush();
+      const byName: CollectedMetrics = new Map();
+      for (const resource of exporter.getMetrics()) {
+        for (const scope of resource.scopeMetrics) {
+          for (const metric of scope.metrics) {
+            byName.set(
+              metric.descriptor.name,
+              metric.dataPoints.map((point) => ({
+                value: point.value,
+                attributes: point.attributes,
+              })),
+            );
+          }
+        }
+      }
+      return byName;
+    },
+    async dispose() {
+      await provider.shutdown();
+      api.metrics.disable();
+      resetInstruments();
+    },
+  };
+}
+
+/** Polls collect() until the predicate holds or the deadline (5 s) passes; returns the last collection either way. */
+export async function until<T>(
+  collect: () => Promise<T>,
+  ready: (collected: T) => boolean,
+): Promise<T> {
+  const deadline = Date.now() + 5_000;
+  for (;;) {
+    const collected = await collect();
+    if (ready(collected) || Date.now() > deadline) {
+      return collected;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 20));
+  }
+}