@graphorin/server 0.5.0

package/dist/index.js

@@ -0,0 +1,86 @@
+import { DEFAULT_APPLY_TO_EVENTS, DEFAULT_DELIVERY_COMMENTARY_PATTERNS } from "./commentary/built-in-patterns.js";
+import { createDeliveryCommentarySanitizer } from "./commentary/sanitizer.js";
+import "./commentary/index.js";
+import { AgentNotFoundError, ConfigInvalidError, GraphorinServerError, IdempotencyConflictError, IdempotencyKeyRequiredError, LifecycleDoubleStartError, LifecycleNotStartedError, MigrationFailedError, PrebindEncryptionPeerMissingError, PrebindEncryptionRequiredError, PrebindPepperMissingError, PrebindSecretUnresolvableError, RouteHandlerMissingError, ShutdownTimeoutError, WorkflowNotFoundError } from "./errors/index.js";
+import { ServerConfigSchema, defineConfig, parseServerConfig } from "./config.js";
+import { createConsolidatorDaemon } from "./consolidator/daemon.js";
+import { collectHealth, rollup } from "./health/checks.js";
+import { createScopeMiddleware } from "./middleware/scope.js";
+import { createExtendedHealthRoutes, createMetricsRoutes, createSecretsHealthRoutes } from "./health/routes.js";
+import "./health/index.js";
+import { runPreBind } from "./lifecycle/pre-bind.js";
+import "./lifecycle/index.js";
+import { MetricRegistry } from "./metrics/registry.js";
+import { SERVER_METRIC_NAMES, createServerMetricRegistry } from "./metrics/catalog.js";
+import { HTTP_REQUEST_AUDIT_ACTION, createAuditMiddleware } from "./middleware/audit.js";
+import { createAuthMiddleware } from "./middleware/auth.js";
+import { createCorsMiddleware } from "./middleware/cors.js";
+import { createCsrfMiddleware } from "./middleware/csrf.js";
+import { createIdempotencyMiddleware } from "./middleware/idempotency.js";
+import { createRateLimitMiddleware } from "./middleware/rate-limit.js";
+import { createRequestStateMiddleware } from "./middleware/request-state.js";
+import "./middleware/index.js";
+import { AgentRegistry, WorkflowRegistry } from "./registry/index.js";
+import { createReplayRoutes } from "./replay/routes.js";
+import "./replay/index.js";
+import { createAgentRoutes, createRunRoutes } from "./routes/agents.js";
+import { createAuditRoutes } from "./routes/audit.js";
+import { createAuthRoutes } from "./routes/auth.js";
+import { createHealthRoutes } from "./routes/health.js";
+import { createMcpRoutes } from "./routes/mcp.js";
+import { createMemoryRoutes } from "./routes/memory.js";
+import { createSessionRoutes } from "./routes/sessions.js";
+import { createSkillsRoutes } from "./routes/skills.js";
+import { createTokensRoutes } from "./routes/tokens.js";
+import { createWorkflowRoutes } from "./routes/workflows.js";
+import "./routes/index.js";
+import { RunStateTracker } from "./runtime/run-state.js";
+import { createSseRoutes } from "./sse/events.js";
+import "./sse/index.js";
+import { createTriggersDaemon, defaultCatchupPolicy } from "./triggers/daemon.js";
+import { createTriggersRoutes } from "./triggers/routes.js";
+import { createReplayBuffer } from "./ws/replay-buffer.js";
+import { requiredScopeFor, tryParseSubject } from "./ws/subjects.js";
+import { createWsDispatcher } from "./ws/dispatcher.js";
+import { createWsTicketStore } from "./ws/ticket.js";
+import { createWsUpgradeEvents } from "./ws/upgrade.js";
+import "./ws/index.js";
+import { createServer, ensureStoreAuditBinding } from "./app.js";
+import "./metrics/index.js";
+import "./triggers/index.js";
+
+//#region src/index.ts
+/**
+* `@graphorin/server` — standalone server runtime for the Graphorin
+* framework.
+*
+* Phase 14a entry point. Ships:
+*
+* - {@link createServer} — the single programmatic entry that wires
+*   the Hono app, the auth + scope + idempotency + audit middleware
+*   stack, REST endpoints (agents / workflows / sessions / memory /
+*   skills / mcp / tokens / audit / health), the lifecycle hooks
+*   (`beforeStart` / `onReady` / `beforeShutdown` / `onError`), the
+*   pre-bind secrets-resolution + storage-migration runner, and the
+*   graceful SIGTERM drain.
+* - {@link defineConfig} + {@link parseServerConfig} — typed
+*   configuration loader with a Zod-validated schema; missing fields
+*   fall back to documented production-ready defaults.
+* - {@link AgentRegistry} + {@link WorkflowRegistry} — read/write
+*   registries the route handlers consult to look up user-defined
+*   agents / workflows.
+* - {@link RunStateTracker} — in-memory bookkeeping for in-flight
+*   runs (run id, status, AbortController). Phase 14b/c promote the
+*   tracker to a SQLite-backed durable variant.
+* - The full middleware factory suite — re-exported from
+*   `@graphorin/server/middleware` so operators can compose a custom
+*   Hono app on top of the same primitives.
+*
+* @packageDocumentation
+*/
+/** Canonical version constant. Mirrors the `package.json` version. */
+const VERSION = "0.5.0";
+
+//#endregion
+export { AgentNotFoundError, AgentRegistry, ConfigInvalidError, DEFAULT_APPLY_TO_EVENTS, DEFAULT_DELIVERY_COMMENTARY_PATTERNS, GraphorinServerError, HTTP_REQUEST_AUDIT_ACTION, IdempotencyConflictError, IdempotencyKeyRequiredError, LifecycleDoubleStartError, LifecycleNotStartedError, MetricRegistry, MigrationFailedError, PrebindEncryptionPeerMissingError, PrebindEncryptionRequiredError, PrebindPepperMissingError, PrebindSecretUnresolvableError, RouteHandlerMissingError, RunStateTracker, SERVER_METRIC_NAMES, ServerConfigSchema, ShutdownTimeoutError, VERSION, WorkflowNotFoundError, WorkflowRegistry, collectHealth, createAgentRoutes, createAuditMiddleware, createAuditRoutes, createAuthMiddleware, createAuthRoutes, createConsolidatorDaemon, createCorsMiddleware, createCsrfMiddleware, createDeliveryCommentarySanitizer, createExtendedHealthRoutes, createHealthRoutes, createIdempotencyMiddleware, createMcpRoutes, createMemoryRoutes, createMetricsRoutes, createRateLimitMiddleware, createReplayBuffer, createReplayRoutes, createRequestStateMiddleware, createRunRoutes, createScopeMiddleware, createSecretsHealthRoutes, createServer, createServerMetricRegistry, createSessionRoutes, createSkillsRoutes, createSseRoutes, createTokensRoutes, createTriggersDaemon, createTriggersRoutes, createWorkflowRoutes, createWsDispatcher, createWsTicketStore, createWsUpgradeEvents, defaultCatchupPolicy, defineConfig, ensureStoreAuditBinding, parseServerConfig, requiredScopeFor, rollup, runPreBind, tryParseSubject };
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["/**\n * `@graphorin/server` — standalone server runtime for the Graphorin\n * framework.\n *\n * Phase 14a entry point. Ships:\n *\n * - {@link createServer} — the single programmatic entry that wires\n *   the Hono app, the auth + scope + idempotency + audit middleware\n *   stack, REST endpoints (agents / workflows / sessions / memory /\n *   skills / mcp / tokens / audit / health), the lifecycle hooks\n *   (`beforeStart` / `onReady` / `beforeShutdown` / `onError`), the\n *   pre-bind secrets-resolution + storage-migration runner, and the\n *   graceful SIGTERM drain.\n * - {@link defineConfig} + {@link parseServerConfig} — typed\n *   configuration loader with a Zod-validated schema; missing fields\n *   fall back to documented production-ready defaults.\n * - {@link AgentRegistry} + {@link WorkflowRegistry} — read/write\n *   registries the route handlers consult to look up user-defined\n *   agents / workflows.\n * - {@link RunStateTracker} — in-memory bookkeeping for in-flight\n *   runs (run id, status, AbortController). Phase 14b/c promote the\n *   tracker to a SQLite-backed durable variant.\n * - The full middleware factory suite — re-exported from\n *   `@graphorin/server/middleware` so operators can compose a custom\n *   Hono app on top of the same primitives.\n *\n * @packageDocumentation\n */\n\n/** Canonical version constant. Mirrors the `package.json` version. */\nexport const VERSION = '0.5.0';\n\nexport {\n  type CreateServerOptions,\n  createServer,\n  ensureStoreAuditBinding,\n  type GraphorinServer,\n  type TriggersDaemonInput,\n} from './app.js';\nexport {\n  createDeliveryCommentarySanitizer,\n  DEFAULT_APPLY_TO_EVENTS,\n  DEFAULT_DELIVERY_COMMENTARY_PATTERNS,\n  type DeliveryCommentaryConfig,\n  type DeliveryCommentaryDecision,\n  type DeliveryCommentaryPattern,\n  type DeliveryCommentaryPolicy,\n  type DeliveryCommentaryReason,\n  type DeliveryCommentarySanitizer,\n  type DeliveryCommentarySink,\n  type DeliveryCommentaryTransport,\n} from './commentary/index.js';\nexport {\n  type DeliveryCommentaryPolicyConfig,\n  defineConfig,\n  type IdempotencyRequireKeyMode,\n  parseServerConfig,\n  type SecretRefString,\n  type SecretsSource,\n  type ServerConfigInput,\n  ServerConfigSchema,\n  type ServerConfigSpec,\n} from './config.js';\nexport {\n  type ConsolidatorDaemon,\n  type ConsolidatorLike,\n  type ConsolidatorStatusLike,\n  type CreateConsolidatorDaemonOptions,\n  createConsolidatorDaemon,\n} from './consolidator/index.js';\nexport * from './errors/index.js';\nexport {\n  type BaseHealthCheck,\n  type ConsolidatorCheck,\n  collectHealth,\n  createExtendedHealthRoutes,\n  createMetricsRoutes,\n  createSecretsHealthRoutes,\n  type EmbedderCheck,\n  type EncryptionCheck,\n  type HealthCheck,\n  type HealthCheckOptions,\n  type HealthChecks,\n  type HealthRollup,\n  type HealthRouteOptions,\n  type HealthStatus,\n  type HealthSummary,\n  type MetricsRoutesOptions,\n  type ReplayBufferCheck,\n  type ReplayBufferProbe,\n  rollup,\n  type SecretsCheck,\n  type StorageCheck,\n  type TriggersCheck,\n} from './health/index.js';\nexport type { RequestToken, ServerRequestState, ServerVariables } from './internal/context.js';\nexport {\n  type BeforeShutdownContext,\n  type BeforeStartContext,\n  type LifecycleHooks,\n  type OnErrorContext,\n  type OnReadyContext,\n  type PreBindResult,\n  type RunPreBindOptions,\n  runPreBind,\n} from './lifecycle/index.js';\nexport {\n  createServerMetricRegistry,\n  type LabelSet,\n  type MetricKind,\n  MetricRegistry,\n  SERVER_METRIC_NAMES,\n} from './metrics/index.js';\nexport {\n  type AuditErrorSink,\n  type AuditMiddlewareOptions,\n  type AuthMiddlewareOptions,\n  createAuditMiddleware,\n  createAuthMiddleware,\n  createCorsMiddleware,\n  createCsrfMiddleware,\n  createIdempotencyMiddleware,\n  createRateLimitMiddleware,\n  createRequestStateMiddleware,\n  createScopeMiddleware,\n  HTTP_REQUEST_AUDIT_ACTION,\n  type IdempotencyMiddlewareOptions,\n  type RequestStateMiddlewareOptions,\n  type ScopeRequirement,\n} from './middleware/index.js';\nexport {\n  type AgentRegistration,\n  AgentRegistry,\n  type AgentSummary,\n  type ServerAgentLike,\n  type ServerWorkflowLike,\n  type WorkflowRegistration,\n  WorkflowRegistry,\n  type WorkflowSummary,\n} from './registry/index.js';\nexport {\n  createReplayRoutes,\n  type ReplayApi,\n  type ReplayMode,\n  type ReplayResponse,\n  type ReplayRoutesDeps,\n} from './replay/index.js';\nexport {\n  type AgentRoutesDeps,\n  type AuditApi,\n  type AuditRoutesDeps,\n  type AuthRoutesDeps,\n  createAgentRoutes,\n  createAuditRoutes,\n  createAuthRoutes,\n  createHealthRoutes,\n  createMcpRoutes,\n  createMemoryRoutes,\n  createRunRoutes,\n  createSessionRoutes,\n  createSkillsRoutes,\n  createTokensRoutes,\n  createWorkflowRoutes,\n  type HealthRoutesDeps,\n  type McpApi,\n  type McpRoutesDeps,\n  type MemoryApi,\n  type MemoryRoutesDeps,\n  type SessionApi,\n  type SessionRoutesDeps,\n  type SkillsApi,\n  type SkillsRoutesDeps,\n  type TokensRoutesDeps,\n  type WorkflowRoutesDeps,\n} from './routes/index.js';\nexport {\n  type RunDescriptor,\n  type RunHandle,\n  type RunStateSnapshot,\n  RunStateTracker,\n  type RunStatus,\n} from './runtime/run-state.js';\nexport { createSseRoutes, type SseRoutesDeps } from './sse/index.js';\nexport {\n  type CreateTriggersDaemonOptions,\n  createTriggersDaemon,\n  createTriggersRoutes,\n  defaultCatchupPolicy,\n  type TriggersDaemon,\n  type TriggersDaemonMetrics,\n  type TriggersDaemonStatus,\n  type TriggersRoutesDeps,\n} from './triggers/index.js';\nexport {\n  type BareEventFrame,\n  createReplayBuffer,\n  createWsDispatcher,\n  createWsTicketStore,\n  createWsUpgradeEvents,\n  type ParsedSubject,\n  type ReplayBuffer,\n  type ReplayBufferOptions,\n  type ReplayBufferSlice,\n  requiredScopeFor,\n  type SubscribeResult,\n  tryParseSubject,\n  type WsDispatcher,\n  type WsDispatcherOptions,\n  type WsDispatcherWarning,\n  type WsSubscriberHandle,\n  type WsSubscriptionSnapshot,\n  type WsTicket,\n  type WsTicketConsumeResult,\n  type WsTicketStore,\n  type WsTicketStoreOptions,\n  type WsUpgradeOptions,\n} from './ws/index.js';\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BA,MAAa,UAAU"}

package/dist/internal/context.d.ts

@@ -0,0 +1,66 @@
+import { ParsedScope, VerifiedToken } from "@graphorin/security/auth";
+
+//#region src/internal/context.d.ts
+
+/**
+ * Discriminator for the request authentication state.
+ *
+ * @stable
+ */
+type AuthState = {
+  readonly kind: 'unauthenticated';
+} | {
+  readonly kind: 'token';
+  readonly token: VerifiedToken;
+  readonly grantedScopes: ReadonlyArray<ParsedScope>;
+} | {
+  readonly kind: 'anonymous';
+  readonly grantedScopes: ReadonlyArray<ParsedScope>;
+};
+/**
+ * Request-scoped variables surfaced through `c.var` in Hono. The
+ * server's middleware populates these fields incrementally; route
+ * handlers consume them through {@link getRequestState}.
+ *
+ * @stable
+ */
+interface ServerRequestState {
+  readonly requestId: string;
+  readonly receivedAt: number;
+  readonly clientIp: string | undefined;
+  readonly auth: AuthState;
+  readonly idempotencyKey?: string;
+  readonly idempotencyReplay?: boolean;
+}
+/**
+ * Convenience snapshot of the verified token surfaced on `c.var.token`
+ * once the auth middleware has resolved the bearer credential. Mirrors
+ * the contract documented in the runtime architecture (Phase 14a §
+ * Authentication / authorization middleware: "populates `c.var.token:
+ * { id, label, scopes, env }`").
+ *
+ * Read this through {@link getRequestToken} so consumers do not have
+ * to remember the variable key.
+ *
+ * @stable
+ */
+interface RequestToken {
+  readonly id: string;
+  readonly label: string | undefined;
+  readonly scopes: ReadonlyArray<ParsedScope>;
+  readonly env: string;
+  readonly expiresAt: number | undefined;
+}
+/**
+ * Hono variable map. Exported so consumers can type their own
+ * middleware against the same surface.
+ *
+ * @stable
+ */
+interface ServerVariables extends Record<string, unknown> {
+  readonly state: ServerRequestState;
+  readonly token?: RequestToken;
+}
+//#endregion
+export { RequestToken, ServerRequestState, ServerVariables };
+//# sourceMappingURL=context.d.ts.map

package/dist/internal/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","names":[],"sources":["../../src/internal/context.ts"],"sourcesContent":[],"mappings":";;;;;;AAsCA;AAqBA;AAcA;AACkB,KA3DN,SAAA,GA2DM;EACC,SAAA,IAAA,EAAA,iBAAA;CAFsB,GAAA;EAAM,SAAA,IAAA,EAAA,OAAA;kBAtDzB;0BACQ,cAAc;;;0BAQd,cAAc;;;;;;;;;UAU3B,kBAAA;;;;iBAIA;;;;;;;;;;;;;;;;UAiBA,YAAA;;;mBAGE,cAAc;;;;;;;;;;UAWhB,eAAA,SAAwB;kBACvB;mBACC"}

package/dist/internal/ids.js

@@ -0,0 +1,21 @@
+import { randomUUID } from "node:crypto";
+
+//#region src/internal/ids.ts
+/**
+* Tiny id helpers shared across middleware + routes.
+*
+* @internal
+*/
+/**
+* Generate an opaque per-request id. UUID v4 keeps the surface area
+* minimal — operators that already pin a different scheme (Datadog
+* trace ids, AWS request ids, …) can override the generator on
+* `createServer({ requestIdGenerator })`.
+*/
+function newRequestId() {
+	return randomUUID();
+}
+
+//#endregion
+export { newRequestId };
+//# sourceMappingURL=ids.js.map

package/dist/internal/ids.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.js","names":[],"sources":["../../src/internal/ids.ts"],"sourcesContent":["/**\n * Tiny id helpers shared across middleware + routes.\n *\n * @internal\n */\n\nimport { randomUUID } from 'node:crypto';\n\n/**\n * Generate an opaque per-request id. UUID v4 keeps the surface area\n * minimal — operators that already pin a different scheme (Datadog\n * trace ids, AWS request ids, …) can override the generator on\n * `createServer({ requestIdGenerator })`.\n */\nexport function newRequestId(): string {\n  return randomUUID();\n}\n"],"mappings":";;;;;;;;;;;;;;AAcA,SAAgB,eAAuB;AACrC,QAAO,YAAY"}

package/dist/internal/json.js

@@ -0,0 +1,46 @@
+import { createHash } from "node:crypto";
+
+//#region src/internal/json.ts
+/**
+* Helpers for the strict JSON contract every REST endpoint speaks.
+*
+* @internal
+*/
+/**
+* Stable, recursive JSON canonicalisation: object keys sorted
+* lexicographically, arrays preserved as-is. Used by the idempotency
+* middleware so two semantically-identical bodies produce the same
+* fingerprint.
+*/
+function canonicalJson(value) {
+	return JSON.stringify(canonicalize(value));
+}
+function canonicalize(value) {
+	if (value === null) return null;
+	if (typeof value !== "object") return value;
+	if (Array.isArray(value)) return value.map(canonicalize);
+	const entries = Object.entries(value).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+	const out = {};
+	for (const [key, val] of entries) out[key] = canonicalize(val);
+	return out;
+}
+/**
+* SHA-256 hex digest of the supplied bytes. Returns the lowercase
+* hex string so it can be compared against the persisted fingerprint
+* without further normalisation.
+*/
+function sha256Hex(input) {
+	return createHash("sha256").update(input).digest("hex");
+}
+/**
+* SHA-256 fingerprint of a (method, path, body) tuple. The body is
+* canonicalised before hashing so trivial whitespace differences do
+* not register as a payload mismatch.
+*/
+function fingerprintRequest(method, path, body) {
+	return sha256Hex(`${method.toUpperCase()} ${path}\n${canonicalJson(body)}`);
+}
+
+//#endregion
+export { fingerprintRequest };
+//# sourceMappingURL=json.js.map

package/dist/internal/json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.js","names":["out: Record<string, unknown>"],"sources":["../../src/internal/json.ts"],"sourcesContent":["/**\n * Helpers for the strict JSON contract every REST endpoint speaks.\n *\n * @internal\n */\n\nimport { createHash } from 'node:crypto';\n\n/**\n * Stable, recursive JSON canonicalisation: object keys sorted\n * lexicographically, arrays preserved as-is. Used by the idempotency\n * middleware so two semantically-identical bodies produce the same\n * fingerprint.\n */\nexport function canonicalJson(value: unknown): string {\n  return JSON.stringify(canonicalize(value));\n}\n\nfunction canonicalize(value: unknown): unknown {\n  if (value === null) return null;\n  if (typeof value !== 'object') return value;\n  if (Array.isArray(value)) return value.map(canonicalize);\n  const entries = Object.entries(value as Record<string, unknown>).sort(([a], [b]) =>\n    a < b ? -1 : a > b ? 1 : 0,\n  );\n  const out: Record<string, unknown> = {};\n  for (const [key, val] of entries) out[key] = canonicalize(val);\n  return out;\n}\n\n/**\n * SHA-256 hex digest of the supplied bytes. Returns the lowercase\n * hex string so it can be compared against the persisted fingerprint\n * without further normalisation.\n */\nexport function sha256Hex(input: string | Uint8Array): string {\n  return createHash('sha256').update(input).digest('hex');\n}\n\n/**\n * SHA-256 fingerprint of a (method, path, body) tuple. The body is\n * canonicalised before hashing so trivial whitespace differences do\n * not register as a payload mismatch.\n */\nexport function fingerprintRequest(method: string, path: string, body: unknown): string {\n  return sha256Hex(`${method.toUpperCase()} ${path}\\n${canonicalJson(body)}`);\n}\n"],"mappings":";;;;;;;;;;;;;;AAcA,SAAgB,cAAc,OAAwB;AACpD,QAAO,KAAK,UAAU,aAAa,MAAM,CAAC;;AAG5C,SAAS,aAAa,OAAyB;AAC7C,KAAI,UAAU,KAAM,QAAO;AAC3B,KAAI,OAAO,UAAU,SAAU,QAAO;AACtC,KAAI,MAAM,QAAQ,MAAM,CAAE,QAAO,MAAM,IAAI,aAAa;CACxD,MAAM,UAAU,OAAO,QAAQ,MAAiC,CAAC,MAAM,CAAC,IAAI,CAAC,OAC3E,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,EAC1B;CACD,MAAMA,MAA+B,EAAE;AACvC,MAAK,MAAM,CAAC,KAAK,QAAQ,QAAS,KAAI,OAAO,aAAa,IAAI;AAC9D,QAAO;;;;;;;AAQT,SAAgB,UAAU,OAAoC;AAC5D,QAAO,WAAW,SAAS,CAAC,OAAO,MAAM,CAAC,OAAO,MAAM;;;;;;;AAQzD,SAAgB,mBAAmB,QAAgB,MAAc,MAAuB;AACtF,QAAO,UAAU,GAAG,OAAO,aAAa,CAAC,GAAG,KAAK,IAAI,cAAc,KAAK,GAAG"}

package/dist/lifecycle/hooks.d.ts

@@ -0,0 +1,57 @@
+import { ServerConfigSpec } from "../config.js";
+
+//#region src/lifecycle/hooks.d.ts
+
+/**
+ * Snapshot passed to {@link LifecycleHooks.beforeStart}.
+ *
+ * @stable
+ */
+interface BeforeStartContext {
+  readonly config: ServerConfigSpec;
+}
+/**
+ * Snapshot passed to {@link LifecycleHooks.onReady}.
+ *
+ * @stable
+ */
+interface OnReadyContext {
+  readonly config: ServerConfigSpec;
+  readonly listeningOn: {
+    readonly host: string;
+    readonly port: number;
+  };
+}
+/**
+ * Snapshot passed to {@link LifecycleHooks.beforeShutdown}.
+ *
+ * @stable
+ */
+interface BeforeShutdownContext {
+  readonly config: ServerConfigSpec;
+  readonly inflight: number;
+  readonly drainTimeoutMs: number;
+}
+/**
+ * Snapshot passed to {@link LifecycleHooks.onError}. Errors raised
+ * outside the request hot path (lifecycle, audit append, etc.) flow
+ * here so operators can fan them into Sentry / Datadog / etc.
+ *
+ * @stable
+ */
+interface OnErrorContext {
+  readonly error: unknown;
+  readonly phase: 'beforeStart' | 'onReady' | 'beforeShutdown' | 'request' | 'background';
+}
+/**
+ * @stable
+ */
+interface LifecycleHooks {
+  readonly beforeStart?: (ctx: BeforeStartContext) => void | Promise<void>;
+  readonly onReady?: (ctx: OnReadyContext) => void | Promise<void>;
+  readonly beforeShutdown?: (ctx: BeforeShutdownContext) => void | Promise<void>;
+  readonly onError?: (ctx: OnErrorContext) => void | Promise<void>;
+}
+//#endregion
+export { BeforeShutdownContext, BeforeStartContext, LifecycleHooks, OnErrorContext, OnReadyContext };
+//# sourceMappingURL=hooks.d.ts.map

package/dist/lifecycle/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","names":[],"sources":["../../src/lifecycle/hooks.ts"],"sourcesContent":[],"mappings":";;;;;;;;;UAoBiB,kBAAA;mBACE;;;;;;;UAQF,cAAA;mBACE;;;;;;;;;;;UASF,qBAAA;mBACE;;;;;;;;;;;UAYF,cAAA;;;;;;;UAQA,cAAA;+BACc,8BAA8B;2BAClC,0BAA0B;kCACnB,iCAAiC;2BACxC,0BAA0B"}

package/dist/lifecycle/index.d.ts

@@ -0,0 +1,2 @@
+import { BeforeShutdownContext, BeforeStartContext, LifecycleHooks, OnErrorContext, OnReadyContext } from "./hooks.js";
+import { PreBindResult, RunPreBindOptions, runPreBind } from "./pre-bind.js";

package/dist/lifecycle/index.js

@@ -0,0 +1,3 @@
+import { runPreBind } from "./pre-bind.js";
+
+export {  };

package/dist/lifecycle/pre-bind.d.ts

@@ -0,0 +1,38 @@
+import { ServerConfigSpec } from "../config.js";
+import { SecretValue } from "@graphorin/security";
+import { GraphorinSqliteStore } from "@graphorin/store-sqlite";
+
+//#region src/lifecycle/pre-bind.d.ts
+
+/**
+ * Result returned by {@link runPreBind}. Consumers (`createServer`,
+ * tests) consume the resolved pepper + encryption decision when
+ * wiring the rest of the server.
+ *
+ * @stable
+ */
+interface PreBindResult {
+  readonly pepper?: SecretValue;
+  readonly auditPath?: string;
+  readonly auditPassphrase?: SecretValue;
+  readonly storagePassphrase?: SecretValue;
+}
+/**
+ * @stable
+ */
+interface RunPreBindOptions {
+  readonly config: ServerConfigSpec;
+  readonly store: GraphorinSqliteStore;
+  /**
+   * Optional override for the cipher-peer probe. Tests inject a stub
+   * that signals "missing peer" without uninstalling the real one.
+   */
+  readonly probeCipherPeer?: () => Promise<void>;
+}
+/**
+ * @stable
+ */
+declare function runPreBind(options: RunPreBindOptions): Promise<PreBindResult>;
+//#endregion
+export { PreBindResult, RunPreBindOptions, runPreBind };
+//# sourceMappingURL=pre-bind.d.ts.map

package/dist/lifecycle/pre-bind.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pre-bind.d.ts","names":[],"sources":["../../src/lifecycle/pre-bind.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;UA0CiB,aAAA;oBACG;;6BAES;+BACE;;;;;UAMd,iBAAA;mBACE;kBACD;;;;;mCAKiB;;;;;iBAcb,UAAA,UAAoB,oBAAoB,QAAQ"}

package/dist/lifecycle/pre-bind.js

@@ -0,0 +1,62 @@
+import { MigrationFailedError, PrebindEncryptionPeerMissingError, PrebindEncryptionRequiredError, PrebindPepperMissingError, PrebindSecretUnresolvableError } from "../errors/index.js";
+import { resolveSecret } from "@graphorin/security/secrets";
+
+//#region src/lifecycle/pre-bind.ts
+async function resolveRef(path, raw) {
+	try {
+		return await resolveSecret(raw);
+	} catch (err) {
+		throw new PrebindSecretUnresolvableError(path, raw, err);
+	}
+}
+/**
+* @stable
+*/
+async function runPreBind(options) {
+	const { config, store } = options;
+	const out = {};
+	if (config.auth.kind === "token") {
+		if (config.auth.pepperRef === void 0 || config.auth.pepperRef.length === 0) throw new PrebindPepperMissingError();
+		const pepper = await resolveRef(["auth", "pepperRef"], config.auth.pepperRef);
+		if ((await pepper.useBuffer((b) => Buffer.from(b))).length === 0) throw new PrebindPepperMissingError();
+		out.pepper = pepper;
+	}
+	if (config.storage.encryption.enabled) {
+		if (config.storage.encryption.passphraseRef === void 0) throw new PrebindEncryptionRequiredError("storage.encryption.enabled is true but no passphraseRef is configured.");
+		out.storagePassphrase = await resolveRef([
+			"storage",
+			"encryption",
+			"passphraseRef"
+		], config.storage.encryption.passphraseRef);
+		if (options.probeCipherPeer !== void 0) try {
+			await options.probeCipherPeer();
+		} catch (err) {
+			throw new PrebindEncryptionPeerMissingError(err);
+		}
+	}
+	if (config.audit.enabled) {
+		const passphraseRef = config.audit.passphraseRef ?? config.storage.encryption.passphraseRef;
+		if (passphraseRef === void 0) throw new PrebindEncryptionRequiredError("audit.enabled is true but no audit.passphraseRef (or storage.encryption.passphraseRef) is configured. Audit logs are mandatory-encrypted (DEC-124).");
+		out.auditPath = config.audit.path ?? deriveAuditPath(config.storage.path);
+		out.auditPassphrase = await resolveRef(["audit", "passphraseRef"], passphraseRef);
+	}
+	try {
+		await store.init();
+	} catch (err) {
+		throw new MigrationFailedError(`Storage migrations failed: ${describeError(err)}`, err);
+	}
+	return Object.freeze(out);
+}
+function deriveAuditPath(storagePath) {
+	const idx = storagePath.lastIndexOf("/");
+	if (idx < 0) return "audit.db";
+	return `${storagePath.slice(0, idx)}/audit.db`;
+}
+function describeError(err) {
+	if (err instanceof Error) return err.message;
+	return String(err);
+}
+
+//#endregion
+export { runPreBind };
+//# sourceMappingURL=pre-bind.js.map

package/dist/lifecycle/pre-bind.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pre-bind.js","names":["out: { -readonly [K in keyof PreBindResult]?: PreBindResult[K] }"],"sources":["../../src/lifecycle/pre-bind.ts"],"sourcesContent":["/**\n * Pre-bind validation. Runs *before* the HTTP listener attaches so a\n * misconfigured server never accepts a single request.\n *\n * Steps (fail-fast on every failure):\n *\n *  1. Resolve every `*Ref` field on the config through the\n *     `@graphorin/security` resolver registry. Missing ref → exit 1.\n *  2. Confirm the server pepper resolved to non-empty bytes.\n *  3. Confirm the encryption peer is loadable when\n *     `storage.encryption.enabled === true` (or `audit.enabled === true`).\n *  4. Run pending storage migrations — failures bubble up as\n *     `MigrationFailedError`.\n *\n * The function is idempotent — calling it more than once for the\n * same {@link createSqliteStore} handle re-validates the secrets but\n * leaves the underlying database untouched.\n *\n * @packageDocumentation\n */\n\nimport type { SecretValue } from '@graphorin/security';\n\nimport { resolveSecret } from '@graphorin/security/secrets';\nimport type { GraphorinSqliteStore } from '@graphorin/store-sqlite';\n\nimport type { ServerConfigSpec } from '../config.js';\nimport {\n  MigrationFailedError,\n  PrebindEncryptionPeerMissingError,\n  PrebindEncryptionRequiredError,\n  PrebindPepperMissingError,\n  PrebindSecretUnresolvableError,\n} from '../errors/index.js';\n\n/**\n * Result returned by {@link runPreBind}. Consumers (`createServer`,\n * tests) consume the resolved pepper + encryption decision when\n * wiring the rest of the server.\n *\n * @stable\n */\nexport interface PreBindResult {\n  readonly pepper?: SecretValue;\n  readonly auditPath?: string;\n  readonly auditPassphrase?: SecretValue;\n  readonly storagePassphrase?: SecretValue;\n}\n\n/**\n * @stable\n */\nexport interface RunPreBindOptions {\n  readonly config: ServerConfigSpec;\n  readonly store: GraphorinSqliteStore;\n  /**\n   * Optional override for the cipher-peer probe. Tests inject a stub\n   * that signals \"missing peer\" without uninstalling the real one.\n   */\n  readonly probeCipherPeer?: () => Promise<void>;\n}\n\nasync function resolveRef(path: ReadonlyArray<string | number>, raw: string): Promise<SecretValue> {\n  try {\n    return await resolveSecret(raw);\n  } catch (err) {\n    throw new PrebindSecretUnresolvableError(path, raw, err);\n  }\n}\n\n/**\n * @stable\n */\nexport async function runPreBind(options: RunPreBindOptions): Promise<PreBindResult> {\n  const { config, store } = options;\n  const out: { -readonly [K in keyof PreBindResult]?: PreBindResult[K] } = {};\n\n  if (config.auth.kind === 'token') {\n    if (config.auth.pepperRef === undefined || config.auth.pepperRef.length === 0) {\n      throw new PrebindPepperMissingError();\n    }\n    const pepper = await resolveRef(['auth', 'pepperRef'], config.auth.pepperRef);\n    const buf = await pepper.useBuffer((b) => Buffer.from(b));\n    if (buf.length === 0) {\n      throw new PrebindPepperMissingError();\n    }\n    out.pepper = pepper;\n  }\n\n  if (config.storage.encryption.enabled) {\n    if (config.storage.encryption.passphraseRef === undefined) {\n      throw new PrebindEncryptionRequiredError(\n        'storage.encryption.enabled is true but no passphraseRef is configured.',\n      );\n    }\n    out.storagePassphrase = await resolveRef(\n      ['storage', 'encryption', 'passphraseRef'],\n      config.storage.encryption.passphraseRef,\n    );\n    if (options.probeCipherPeer !== undefined) {\n      try {\n        await options.probeCipherPeer();\n      } catch (err) {\n        throw new PrebindEncryptionPeerMissingError(err);\n      }\n    }\n  }\n\n  if (config.audit.enabled) {\n    const passphraseRef = config.audit.passphraseRef ?? config.storage.encryption.passphraseRef;\n    if (passphraseRef === undefined) {\n      throw new PrebindEncryptionRequiredError(\n        'audit.enabled is true but no audit.passphraseRef (or storage.encryption.passphraseRef) is configured. Audit logs are mandatory-encrypted (DEC-124).',\n      );\n    }\n    out.auditPath = config.audit.path ?? deriveAuditPath(config.storage.path);\n    out.auditPassphrase = await resolveRef(['audit', 'passphraseRef'], passphraseRef);\n  }\n\n  try {\n    await store.init();\n  } catch (err) {\n    throw new MigrationFailedError(`Storage migrations failed: ${describeError(err)}`, err);\n  }\n\n  return Object.freeze(out as PreBindResult);\n}\n\nfunction deriveAuditPath(storagePath: string): string {\n  const idx = storagePath.lastIndexOf('/');\n  if (idx < 0) return 'audit.db';\n  return `${storagePath.slice(0, idx)}/audit.db`;\n}\n\nfunction describeError(err: unknown): string {\n  if (err instanceof Error) return err.message;\n  return String(err);\n}\n"],"mappings":";;;;AA8DA,eAAe,WAAW,MAAsC,KAAmC;AACjG,KAAI;AACF,SAAO,MAAM,cAAc,IAAI;UACxB,KAAK;AACZ,QAAM,IAAI,+BAA+B,MAAM,KAAK,IAAI;;;;;;AAO5D,eAAsB,WAAW,SAAoD;CACnF,MAAM,EAAE,QAAQ,UAAU;CAC1B,MAAMA,MAAmE,EAAE;AAE3E,KAAI,OAAO,KAAK,SAAS,SAAS;AAChC,MAAI,OAAO,KAAK,cAAc,UAAa,OAAO,KAAK,UAAU,WAAW,EAC1E,OAAM,IAAI,2BAA2B;EAEvC,MAAM,SAAS,MAAM,WAAW,CAAC,QAAQ,YAAY,EAAE,OAAO,KAAK,UAAU;AAE7E,OADY,MAAM,OAAO,WAAW,MAAM,OAAO,KAAK,EAAE,CAAC,EACjD,WAAW,EACjB,OAAM,IAAI,2BAA2B;AAEvC,MAAI,SAAS;;AAGf,KAAI,OAAO,QAAQ,WAAW,SAAS;AACrC,MAAI,OAAO,QAAQ,WAAW,kBAAkB,OAC9C,OAAM,IAAI,+BACR,yEACD;AAEH,MAAI,oBAAoB,MAAM,WAC5B;GAAC;GAAW;GAAc;GAAgB,EAC1C,OAAO,QAAQ,WAAW,cAC3B;AACD,MAAI,QAAQ,oBAAoB,OAC9B,KAAI;AACF,SAAM,QAAQ,iBAAiB;WACxB,KAAK;AACZ,SAAM,IAAI,kCAAkC,IAAI;;;AAKtD,KAAI,OAAO,MAAM,SAAS;EACxB,MAAM,gBAAgB,OAAO,MAAM,iBAAiB,OAAO,QAAQ,WAAW;AAC9E,MAAI,kBAAkB,OACpB,OAAM,IAAI,+BACR,sJACD;AAEH,MAAI,YAAY,OAAO,MAAM,QAAQ,gBAAgB,OAAO,QAAQ,KAAK;AACzE,MAAI,kBAAkB,MAAM,WAAW,CAAC,SAAS,gBAAgB,EAAE,cAAc;;AAGnF,KAAI;AACF,QAAM,MAAM,MAAM;UACX,KAAK;AACZ,QAAM,IAAI,qBAAqB,8BAA8B,cAAc,IAAI,IAAI,IAAI;;AAGzF,QAAO,OAAO,OAAO,IAAqB;;AAG5C,SAAS,gBAAgB,aAA6B;CACpD,MAAM,MAAM,YAAY,YAAY,IAAI;AACxC,KAAI,MAAM,EAAG,QAAO;AACpB,QAAO,GAAG,YAAY,MAAM,GAAG,IAAI,CAAC;;AAGtC,SAAS,cAAc,KAAsB;AAC3C,KAAI,eAAe,MAAO,QAAO,IAAI;AACrC,QAAO,OAAO,IAAI"}

package/dist/metrics/catalog.d.ts

@@ -0,0 +1,34 @@
+import { MetricRegistry } from "./registry.js";
+
+//#region src/metrics/catalog.d.ts
+
+/**
+ * @stable
+ */
+declare const SERVER_METRIC_NAMES: Readonly<{
+  readonly agentRunsTotal: "graphorin_agent_runs_total";
+  readonly agentRunDuration: "graphorin_agent_run_duration_seconds";
+  readonly storageWalSize: "graphorin_storage_wal_size_bytes";
+  readonly idempotencyCacheHitRatio: "graphorin_idempotency_cache_hit_ratio";
+  readonly triggersFiresTotal: "graphorin_triggers_fires_total";
+  readonly consolidatorQueueDepth: "graphorin_consolidator_queue_depth";
+  readonly consolidatorDlqSize: "graphorin_consolidator_dlq_size";
+  readonly consolidatorBudgetRemainingUsd: "graphorin_consolidator_budget_remaining_usd";
+  readonly consolidatorBudgetRemainingTokens: "graphorin_consolidator_budget_remaining_tokens";
+  readonly replayBufferEvents: "graphorin_replay_buffer_events";
+  readonly inflightRuns: "graphorin_inflight_runs";
+  readonly serverUptime: "graphorin_server_uptime_seconds";
+  readonly buildInfo: "graphorin_build_info";
+}>;
+/**
+ * Build a fully-registered {@link MetricRegistry} ready for the
+ * `/v1/metrics` exposition. The returned registry has every metric
+ * declared but no samples; the server runtime updates samples
+ * incrementally.
+ *
+ * @stable
+ */
+declare function createServerMetricRegistry(): MetricRegistry;
+//#endregion
+export { SERVER_METRIC_NAMES, createServerMetricRegistry };
+//# sourceMappingURL=catalog.d.ts.map

package/dist/metrics/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","names":[],"sources":["../../src/metrics/catalog.ts"],"sourcesContent":[],"mappings":";;;;;;;cA0Ba,qBAAmB;;;;;;;;;;;;;;;;;;;;;;;iBAwBhB,0BAAA,CAAA,GAA8B"}

package/dist/metrics/catalog.js

@@ -0,0 +1,61 @@
+import { MetricRegistry } from "./registry.js";
+
+//#region src/metrics/catalog.ts
+/**
+* Canonical metric inventory for the standalone server. Every metric
+* the framework emits is registered here in one place so the
+* exposition output is deterministic across builds.
+*
+* Metric naming follows the documented `graphorin_*` prefix
+* discipline; label cardinality is bounded by construction (no PII
+* labels — see DEC-141 cross-cut).
+*
+* @packageDocumentation
+*/
+/**
+* @stable
+*/
+const SERVER_METRIC_NAMES = Object.freeze({
+	agentRunsTotal: "graphorin_agent_runs_total",
+	agentRunDuration: "graphorin_agent_run_duration_seconds",
+	storageWalSize: "graphorin_storage_wal_size_bytes",
+	idempotencyCacheHitRatio: "graphorin_idempotency_cache_hit_ratio",
+	triggersFiresTotal: "graphorin_triggers_fires_total",
+	consolidatorQueueDepth: "graphorin_consolidator_queue_depth",
+	consolidatorDlqSize: "graphorin_consolidator_dlq_size",
+	consolidatorBudgetRemainingUsd: "graphorin_consolidator_budget_remaining_usd",
+	consolidatorBudgetRemainingTokens: "graphorin_consolidator_budget_remaining_tokens",
+	replayBufferEvents: "graphorin_replay_buffer_events",
+	inflightRuns: "graphorin_inflight_runs",
+	serverUptime: "graphorin_server_uptime_seconds",
+	buildInfo: "graphorin_build_info"
+});
+/**
+* Build a fully-registered {@link MetricRegistry} ready for the
+* `/v1/metrics` exposition. The returned registry has every metric
+* declared but no samples; the server runtime updates samples
+* incrementally.
+*
+* @stable
+*/
+function createServerMetricRegistry() {
+	const registry = new MetricRegistry();
+	registry.registerCounter(SERVER_METRIC_NAMES.agentRunsTotal, "Total agent runs by terminal status.", ["status"]);
+	registry.registerSummary(SERVER_METRIC_NAMES.agentRunDuration, "Agent run duration in seconds.", []);
+	registry.registerGauge(SERVER_METRIC_NAMES.storageWalSize, "Current SQLite WAL size in bytes.");
+	registry.registerGauge(SERVER_METRIC_NAMES.idempotencyCacheHitRatio, "Idempotency LRU cache hit ratio in [0, 1].");
+	registry.registerCounter(SERVER_METRIC_NAMES.triggersFiresTotal, "Total trigger fires by trigger id and outcome.", ["trigger_id", "status"]);
+	registry.registerGauge(SERVER_METRIC_NAMES.consolidatorQueueDepth, "Pending consolidator items by phase.", ["phase"]);
+	registry.registerGauge(SERVER_METRIC_NAMES.consolidatorDlqSize, "Number of consolidator runs sitting in the dead-letter queue.");
+	registry.registerGauge(SERVER_METRIC_NAMES.consolidatorBudgetRemainingUsd, "Consolidator USD budget remaining for the current period.");
+	registry.registerGauge(SERVER_METRIC_NAMES.consolidatorBudgetRemainingTokens, "Consolidator token budget remaining for the current period.");
+	registry.registerGauge(SERVER_METRIC_NAMES.replayBufferEvents, "Number of events currently buffered for WebSocket replay.");
+	registry.registerGauge(SERVER_METRIC_NAMES.inflightRuns, "Number of in-flight agent / workflow runs.");
+	registry.registerGauge(SERVER_METRIC_NAMES.serverUptime, "Server process uptime in seconds.");
+	registry.registerGauge(SERVER_METRIC_NAMES.buildInfo, "Static `1` gauge carrying graphorin build labels.", ["version"]);
+	return registry;
+}
+
+//#endregion
+export { SERVER_METRIC_NAMES, createServerMetricRegistry };
+//# sourceMappingURL=catalog.js.map

package/dist/metrics/catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.js","names":[],"sources":["../../src/metrics/catalog.ts"],"sourcesContent":["/**\n * Canonical metric inventory for the standalone server. Every metric\n * the framework emits is registered here in one place so the\n * exposition output is deterministic across builds.\n *\n * Metric naming follows the documented `graphorin_*` prefix\n * discipline; label cardinality is bounded by construction (no PII\n * labels — see DEC-141 cross-cut).\n *\n * @packageDocumentation\n */\n\nimport { MetricRegistry } from './registry.js';\n\n/**\n * @stable\n */\n// IP-15: the catalog lists only metrics the server actually moves. Five\n// previously-registered series — `graphorin_tool_calls_total`,\n// `graphorin_provider_tokens_total`, `graphorin_provider_cost_usd_total`,\n// `graphorin_redaction_drops_total` and `graphorin_oauth_tokens_freshness_seconds`\n// — had no producer anywhere in the monorepo (per-tool and provider usage live\n// in the agent runtime, not the server; redaction drops in the observability\n// layer; OAuth freshness needs an MCP token store the server does not own). A\n// permanently-empty series is worse than an absent one for dashboards, so they\n// are dropped until a real producer exists rather than advertised inert.\nexport const SERVER_METRIC_NAMES = Object.freeze({\n  agentRunsTotal: 'graphorin_agent_runs_total',\n  agentRunDuration: 'graphorin_agent_run_duration_seconds',\n  storageWalSize: 'graphorin_storage_wal_size_bytes',\n  idempotencyCacheHitRatio: 'graphorin_idempotency_cache_hit_ratio',\n  triggersFiresTotal: 'graphorin_triggers_fires_total',\n  consolidatorQueueDepth: 'graphorin_consolidator_queue_depth',\n  consolidatorDlqSize: 'graphorin_consolidator_dlq_size',\n  consolidatorBudgetRemainingUsd: 'graphorin_consolidator_budget_remaining_usd',\n  consolidatorBudgetRemainingTokens: 'graphorin_consolidator_budget_remaining_tokens',\n  replayBufferEvents: 'graphorin_replay_buffer_events',\n  inflightRuns: 'graphorin_inflight_runs',\n  serverUptime: 'graphorin_server_uptime_seconds',\n  buildInfo: 'graphorin_build_info',\n} as const);\n\n/**\n * Build a fully-registered {@link MetricRegistry} ready for the\n * `/v1/metrics` exposition. The returned registry has every metric\n * declared but no samples; the server runtime updates samples\n * incrementally.\n *\n * @stable\n */\nexport function createServerMetricRegistry(): MetricRegistry {\n  const registry = new MetricRegistry();\n\n  registry.registerCounter(\n    SERVER_METRIC_NAMES.agentRunsTotal,\n    'Total agent runs by terminal status.',\n    ['status'],\n  );\n  registry.registerSummary(\n    SERVER_METRIC_NAMES.agentRunDuration,\n    'Agent run duration in seconds.',\n    [],\n  );\n  registry.registerGauge(SERVER_METRIC_NAMES.storageWalSize, 'Current SQLite WAL size in bytes.');\n  registry.registerGauge(\n    SERVER_METRIC_NAMES.idempotencyCacheHitRatio,\n    'Idempotency LRU cache hit ratio in [0, 1].',\n  );\n  registry.registerCounter(\n    SERVER_METRIC_NAMES.triggersFiresTotal,\n    'Total trigger fires by trigger id and outcome.',\n    ['trigger_id', 'status'],\n  );\n  registry.registerGauge(\n    SERVER_METRIC_NAMES.consolidatorQueueDepth,\n    'Pending consolidator items by phase.',\n    ['phase'],\n  );\n  registry.registerGauge(\n    SERVER_METRIC_NAMES.consolidatorDlqSize,\n    'Number of consolidator runs sitting in the dead-letter queue.',\n  );\n  registry.registerGauge(\n    SERVER_METRIC_NAMES.consolidatorBudgetRemainingUsd,\n    'Consolidator USD budget remaining for the current period.',\n  );\n  registry.registerGauge(\n    SERVER_METRIC_NAMES.consolidatorBudgetRemainingTokens,\n    'Consolidator token budget remaining for the current period.',\n  );\n  registry.registerGauge(\n    SERVER_METRIC_NAMES.replayBufferEvents,\n    'Number of events currently buffered for WebSocket replay.',\n  );\n  registry.registerGauge(\n    SERVER_METRIC_NAMES.inflightRuns,\n    'Number of in-flight agent / workflow runs.',\n  );\n  registry.registerGauge(SERVER_METRIC_NAMES.serverUptime, 'Server process uptime in seconds.');\n  registry.registerGauge(\n    SERVER_METRIC_NAMES.buildInfo,\n    'Static `1` gauge carrying graphorin build labels.',\n    ['version'],\n  );\n\n  return registry;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AA0BA,MAAa,sBAAsB,OAAO,OAAO;CAC/C,gBAAgB;CAChB,kBAAkB;CAClB,gBAAgB;CAChB,0BAA0B;CAC1B,oBAAoB;CACpB,wBAAwB;CACxB,qBAAqB;CACrB,gCAAgC;CAChC,mCAAmC;CACnC,oBAAoB;CACpB,cAAc;CACd,cAAc;CACd,WAAW;CACZ,CAAU;;;;;;;;;AAUX,SAAgB,6BAA6C;CAC3D,MAAM,WAAW,IAAI,gBAAgB;AAErC,UAAS,gBACP,oBAAoB,gBACpB,wCACA,CAAC,SAAS,CACX;AACD,UAAS,gBACP,oBAAoB,kBACpB,kCACA,EAAE,CACH;AACD,UAAS,cAAc,oBAAoB,gBAAgB,oCAAoC;AAC/F,UAAS,cACP,oBAAoB,0BACpB,6CACD;AACD,UAAS,gBACP,oBAAoB,oBACpB,kDACA,CAAC,cAAc,SAAS,CACzB;AACD,UAAS,cACP,oBAAoB,wBACpB,wCACA,CAAC,QAAQ,CACV;AACD,UAAS,cACP,oBAAoB,qBACpB,gEACD;AACD,UAAS,cACP,oBAAoB,gCACpB,4DACD;AACD,UAAS,cACP,oBAAoB,mCACpB,8DACD;AACD,UAAS,cACP,oBAAoB,oBACpB,4DACD;AACD,UAAS,cACP,oBAAoB,cACpB,6CACD;AACD,UAAS,cAAc,oBAAoB,cAAc,oCAAoC;AAC7F,UAAS,cACP,oBAAoB,WACpB,qDACA,CAAC,UAAU,CACZ;AAED,QAAO"}

package/dist/metrics/index.d.ts

@@ -0,0 +1,3 @@
+import { LabelSet, MetricKind, MetricRegistry } from "./registry.js";
+import { SERVER_METRIC_NAMES, createServerMetricRegistry } from "./catalog.js";
+export { type LabelSet, type MetricKind, MetricRegistry, SERVER_METRIC_NAMES, createServerMetricRegistry };

package/dist/metrics/index.js

@@ -0,0 +1,4 @@
+import { MetricRegistry } from "./registry.js";
+import { SERVER_METRIC_NAMES, createServerMetricRegistry } from "./catalog.js";
+
+export { MetricRegistry, SERVER_METRIC_NAMES, createServerMetricRegistry };

package/dist/metrics/registry.d.ts

@@ -0,0 +1,63 @@
+//#region src/metrics/registry.d.ts
+/**
+ * Tiny Prometheus exposition layer. The framework intentionally does
+ * not pull in `prom-client` so the bundle stays lean and so the
+ * exposition is byte-stable across processes (`prom-client` adds
+ * default counters that drift between Node releases).
+ *
+ * The supported metric kinds are the three the runtime spec calls
+ * out: `counter`, `gauge`, and `summary` (with hard-coded p50/p95
+ * quantiles). Sample rendering follows Prometheus text exposition
+ * format v0.0.4 — every metric block is preceded by `# HELP` + `# TYPE`
+ * and labels are quoted-escaped per the spec.
+ *
+ * @packageDocumentation
+ */
+/** @stable */
+type MetricKind = 'counter' | 'gauge' | 'summary';
+/** @stable */
+type LabelSet = Readonly<Record<string, string | number | boolean>>;
+/**
+ * Lightweight Prometheus registry. Each instance owns its metric
+ * catalogue + per-label samples; `render()` emits the canonical text
+ * exposition block.
+ *
+ * @stable
+ */
+declare class MetricRegistry {
+  #private;
+  registerCounter(name: string, help: string, labelNames?: ReadonlyArray<string>): void;
+  registerGauge(name: string, help: string, labelNames?: ReadonlyArray<string>): void;
+  registerSummary(name: string, help: string, labelNames?: ReadonlyArray<string>): void;
+  inc(name: string, labels?: LabelSet, by?: number): void;
+  set(name: string, value: number, labels?: LabelSet): void;
+  observe(name: string, value: number, labels?: LabelSet): void;
+  reset(): void;
+  /**
+   * Render the current snapshot in Prometheus text exposition
+   * format (v0.0.4). Never throws — incomplete sample buckets are
+   * skipped instead of failing the scrape.
+   */
+  render(): string;
+  contentType(): string;
+  /** Snapshot for tests / assertions. */
+  snapshot(): {
+    counters: Record<string, ReadonlyArray<{
+      labels: LabelSet;
+      value: number;
+    }>>;
+    gauges: Record<string, ReadonlyArray<{
+      labels: LabelSet;
+      value: number;
+    }>>;
+    summaries: Record<string, ReadonlyArray<{
+      labels: LabelSet;
+      count: number;
+      sum: number;
+      samples: ReadonlyArray<number>;
+    }>>;
+  };
+}
+//#endregion
+export { LabelSet, MetricKind, MetricRegistry };
+//# sourceMappingURL=registry.d.ts.map

package/dist/metrics/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","names":[],"sources":["../../src/metrics/registry.ts"],"sourcesContent":[],"mappings":";;AAgBA;AAGA;AAqCA;;;;;;;;;;;;AAkJY,KA1LA,UAAA,GA0LA,SAAA,GAAA,OAAA,GAAA,SAAA;;AAOK,KA9LL,QAAA,GAAW,QA8LN,CA9Le,MA8Lf,CAAA,MAAA,EAAA,MAAA,GAAA,MAAA,GAAA,OAAA,CAAA,CAAA;;;;;;;;cAzJJ,cAAA;;2DAM6C;yDAKF;2DAKE;6BAK9B;4CAmBe;gDAWI;;;;;;;;;;;cA8FjC,eAAe;cAAwB;;;YACzC,eAAe;cAAwB;;;eACpC,eAET;cACU;;;eAGC"}