@graphorin/server 0.5.0

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","names":[],"sources":["../src/config.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;AA0WA;;;KA9UY,eAAA;;;;;;;KAQA,aAAA;;KAGA,yBAAA;;KAGA,8BAAA;;UAGK,gBAAA;;;;;;6BAMY;;6BAEA;6BACA;;;;;;;4BAOD;;;;;;;;;2BASD;;;;;;;;;;;;;;;;;;;;;;;yBAuBF;gCACO;;;;;;;;;;;;;;;;+BAgBD;;;;;;6BAMF;;;;qBAIR;;;;;yBAKI;;gCAEO;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA2OnB,oBAAkB,CAAA,CAAA,WAAA,CAAA,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAAA,YAAA,EAAA,MAAA;IAAA,CAAA,EAAA;MAAA,OAAA,CAAA,EAAA,OAAA,GAAA,SAAA;MAqBnB,UAAA,CAAA,EAAiB,KAAA,GAAA,MAAkB,GAAA,SAAA,GAAA,SAAR;MAUvB,UAAY,CAAA,EAAA,MAAQ,GAAA,SAAA;MAWpB,oBAAiB,CAAA,EAAkB,OAAA,GAAA,SAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KArBvD,iBAAA,GAAoB,CAAA,CAAE,aAAa;;;;;;;;;iBAU/B,YAAA,QAAoB,oBAAoB;;;;;;;;iBAWxC,iBAAA,kBAAmC"}

package/dist/config.js

@@ -0,0 +1,217 @@
+import { ConfigInvalidError } from "./errors/index.js";
+import { z } from "zod";
+
+//#region src/config.ts
+/**
+* Strongly-typed configuration loader for the Graphorin server.
+*
+* Operators ship a `graphorin.config.ts` (or `.js` / `.mjs` / JSON)
+* file that calls {@link defineConfig} to construct a typed config
+* object; the server runtime accepts either the raw object, a path
+* to such a file, or a function that returns one.
+*
+* Validation is performed via Zod so user-facing errors include the
+* exact path of every failing field, not just a generic
+* "TypeError: undefined".
+*
+* @packageDocumentation
+*/
+const corsSchema = z.object({
+	allowOrigins: z.array(z.string()).default([]),
+	allowCredentials: z.boolean().default(false),
+	allowMethods: z.array(z.string()).default([
+		"GET",
+		"POST",
+		"PUT",
+		"PATCH",
+		"DELETE",
+		"OPTIONS"
+	]),
+	allowHeaders: z.array(z.string()).default([
+		"Authorization",
+		"Content-Type",
+		"Idempotency-Key",
+		"X-CSRF-Token"
+	]),
+	maxAgeSeconds: z.number().int().nonnegative().default(600)
+}).strict().default({});
+const csrfSchema = z.object({
+	enabled: z.boolean().default(true),
+	cookieName: z.string().default("graphorin_csrf"),
+	headerName: z.string().default("X-CSRF-Token"),
+	safeMethods: z.array(z.string()).default([
+		"GET",
+		"HEAD",
+		"OPTIONS"
+	])
+}).strict().default({});
+const rateLimitSchema = z.object({
+	enabled: z.boolean().default(true),
+	windowMs: z.number().int().positive().default(6e4),
+	perIpRequests: z.number().int().positive().default(60)
+}).strict().default({});
+const idempotencySchema = z.object({
+	enabled: z.boolean().default(true),
+	requireKey: z.enum([
+		"off",
+		"warn",
+		"enforce"
+	]).default("warn"),
+	ttlSeconds: z.number().int().positive().default(86400),
+	checkBodyFingerprint: z.boolean().default(true),
+	lruCacheSize: z.number().int().positive().default(1e3)
+}).strict().default({});
+const shutdownSchema = z.object({ drainTimeoutMs: z.number().int().positive().default(3e4) }).strict().default({});
+const streamReplayBufferSchema = z.object({
+	maxEvents: z.number().int().positive().default(1e3),
+	ttlSeconds: z.number().int().positive().default(300)
+}).strict().default({});
+const streamSchema = z.object({
+	disconnectPolicy: z.enum([
+		"continue",
+		"pause-on-disconnect",
+		"abort-on-disconnect"
+	]).default("continue"),
+	disconnectGracePeriodMs: z.number().int().nonnegative().default(1e4),
+	replayBuffer: streamReplayBufferSchema,
+	perConnectionQueueLimit: z.number().int().positive().default(1e3)
+}).strict().default({});
+const wsCommentarySchema = z.object({
+	policy: z.enum([
+		"wrap",
+		"strip",
+		"pass-through"
+	]).default("wrap"),
+	applyToEvents: z.array(z.string().min(1)).default([
+		"tool.execute.end",
+		"tool.execute.error",
+		"text.delta"
+	])
+}).strict().default({});
+const wsSchema = z.object({
+	enabled: z.boolean().default(true),
+	path: z.string().default("/ws"),
+	ticketTtlMs: z.number().int().positive().default(5 * 6e4),
+	commentarySanitization: wsCommentarySchema
+}).strict().default({});
+const sseSchema = z.object({
+	enabled: z.boolean().default(true),
+	path: z.string().default("/sessions"),
+	keepAliveMs: z.number().int().positive().default(15e3)
+}).strict().default({});
+const serverSchema = z.object({
+	host: z.string().min(1).default("127.0.0.1"),
+	port: z.number().int().min(0).max(65535).default(8080),
+	basePath: z.string().default("/v1"),
+	cors: corsSchema,
+	csrf: csrfSchema,
+	rateLimit: rateLimitSchema,
+	idempotency: idempotencySchema,
+	shutdown: shutdownSchema,
+	trustProxy: z.boolean().default(false),
+	stream: streamSchema,
+	ws: wsSchema,
+	sse: sseSchema
+}).strict().default({});
+const encryptionSchema = z.object({
+	enabled: z.boolean().default(false),
+	cipher: z.string().optional(),
+	passphraseRef: z.string().optional()
+}).strict().default({});
+const storageSchema = z.object({
+	path: z.string().min(1).default("./.graphorin/data.db"),
+	mode: z.enum(["lib", "server"]).default("server"),
+	walCheckpointIntervalMs: z.number().int().positive().optional(),
+	encryption: encryptionSchema
+}).strict().default({});
+const auditSchema = z.object({
+	enabled: z.boolean().default(false),
+	path: z.string().optional(),
+	passphraseRef: z.string().optional(),
+	cipher: z.string().optional()
+}).strict().default({});
+const secretsSchema = z.object({
+	source: z.enum([
+		"auto",
+		"keyring",
+		"encrypted-file",
+		"env"
+	]).default("auto"),
+	strict: z.boolean().default(false)
+}).strict().default({});
+const authSchema = z.object({
+	kind: z.enum(["token", "none"]).default("token"),
+	pepperRef: z.string().optional(),
+	tokenPrefix: z.string().default("gph"),
+	tokenEnvironments: z.array(z.string()).default([
+		"live",
+		"test",
+		"local"
+	]),
+	perIpFailureThreshold: z.number().int().positive().optional(),
+	perIpLockoutMs: z.number().int().positive().optional()
+}).strict().default({});
+const observabilitySchema = z.object({ logger: z.enum([
+	"json",
+	"pretty",
+	"silent"
+]).default("json") }).strict().default({});
+const hardeningSchema = z.object({
+	applyOnStart: z.boolean().default(true),
+	refuseRoot: z.boolean().default(true),
+	umask: z.number().int().nonnegative().default(63)
+}).strict().default({});
+const metricsSchema = z.object({
+	enabled: z.boolean().default(true),
+	path: z.string().default("/metrics"),
+	requireAuth: z.boolean().default(false)
+}).strict().default({});
+const healthSchema = z.object({ walWarnThresholdBytes: z.number().int().positive().default(50 * 1024 * 1024) }).strict().default({});
+/**
+* Zod schema for the resolved {@link ServerConfigSpec}. Exposed for
+* advanced users that want to validate other config sources (env-only
+* launch, CLI overrides, etc.).
+*
+* @stable
+*/
+const ServerConfigSchema = z.object({
+	server: serverSchema,
+	storage: storageSchema,
+	audit: auditSchema,
+	secrets: secretsSchema,
+	auth: authSchema,
+	observability: observabilitySchema,
+	hardening: hardeningSchema,
+	metrics: metricsSchema,
+	health: healthSchema
+}).strict().default({});
+/**
+* Helper for `graphorin.config.ts` files. Pure pass-through that
+* provides editor autocomplete; the actual parsing happens at server
+* startup so callers always see the same error path regardless of
+* which loader (TS / JS / JSON) the operator picked.
+*
+* @stable
+*/
+function defineConfig(input) {
+	return input;
+}
+/**
+* Parse + validate user input. Returns a strongly-typed
+* {@link ServerConfigSpec}; throws {@link ConfigInvalidError} on
+* any invalid field with a flattened issue list.
+*
+* @stable
+*/
+function parseServerConfig(input) {
+	const result = ServerConfigSchema.safeParse(input ?? {});
+	if (!result.success) throw new ConfigInvalidError(result.error.issues.map((issue) => ({
+		path: issue.path,
+		message: issue.message
+	})), result.error);
+	return result.data;
+}
+
+//#endregion
+export { ServerConfigSchema, defineConfig, parseServerConfig };
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","names":[],"sources":["../src/config.ts"],"sourcesContent":["/**\n * Strongly-typed configuration loader for the Graphorin server.\n *\n * Operators ship a `graphorin.config.ts` (or `.js` / `.mjs` / JSON)\n * file that calls {@link defineConfig} to construct a typed config\n * object; the server runtime accepts either the raw object, a path\n * to such a file, or a function that returns one.\n *\n * Validation is performed via Zod so user-facing errors include the\n * exact path of every failing field, not just a generic\n * \"TypeError: undefined\".\n *\n * @packageDocumentation\n */\n\nimport { z } from 'zod';\n\nimport { ConfigInvalidError } from './errors/index.js';\n\n/**\n * String literal that flags a value as a `SecretRef` URI. The\n * server's pre-bind step resolves every `*Ref` field through the\n * `@graphorin/security` resolver registry before binding the\n * listener; an unresolvable ref fails fast with\n * {@link import('./errors/index.js').PrebindSecretUnresolvableError}.\n *\n * @stable\n */\nexport type SecretRefString = string;\n\n/**\n * Selector for which `SecretsStore` flavour the server activates.\n * Mirrors `--secrets-source` from DEC-136.\n *\n * @stable\n */\nexport type SecretsSource = 'auto' | 'keyring' | 'encrypted-file' | 'env';\n\n/** @stable */\nexport type IdempotencyRequireKeyMode = 'off' | 'warn' | 'enforce';\n\n/** @stable */\nexport type DeliveryCommentaryPolicyConfig = 'wrap' | 'strip' | 'pass-through';\n\n/** @stable */\nexport interface ServerConfigSpec {\n  readonly server: {\n    readonly host: string;\n    readonly port: number;\n    readonly basePath: string;\n    readonly cors: {\n      readonly allowOrigins: ReadonlyArray<string>;\n      readonly allowCredentials: boolean;\n      readonly allowMethods: ReadonlyArray<string>;\n      readonly allowHeaders: ReadonlyArray<string>;\n      readonly maxAgeSeconds: number;\n    };\n    readonly csrf: {\n      readonly enabled: boolean;\n      readonly cookieName: string;\n      readonly headerName: string;\n      readonly safeMethods: ReadonlyArray<string>;\n    };\n    readonly rateLimit: {\n      readonly enabled: boolean;\n      readonly windowMs: number;\n      readonly perIpRequests: number;\n    };\n    readonly idempotency: {\n      readonly enabled: boolean;\n      readonly requireKey: IdempotencyRequireKeyMode;\n      readonly ttlSeconds: number;\n      readonly checkBodyFingerprint: boolean;\n      readonly lruCacheSize: number;\n    };\n    readonly shutdown: {\n      readonly drainTimeoutMs: number;\n    };\n    readonly trustProxy: boolean;\n    readonly stream: {\n      readonly disconnectPolicy: 'continue' | 'pause-on-disconnect' | 'abort-on-disconnect';\n      readonly disconnectGracePeriodMs: number;\n      readonly replayBuffer: {\n        readonly maxEvents: number;\n        readonly ttlSeconds: number;\n      };\n      readonly perConnectionQueueLimit: number;\n    };\n    readonly ws: {\n      readonly enabled: boolean;\n      readonly path: string;\n      readonly ticketTtlMs: number;\n      readonly commentarySanitization: {\n        readonly policy: DeliveryCommentaryPolicyConfig;\n        readonly applyToEvents: ReadonlyArray<string>;\n      };\n    };\n    readonly sse: {\n      readonly enabled: boolean;\n      readonly path: string;\n      readonly keepAliveMs: number;\n    };\n  };\n  readonly storage: {\n    readonly path: string;\n    readonly mode: 'lib' | 'server';\n    readonly walCheckpointIntervalMs?: number;\n    readonly encryption: {\n      readonly enabled: boolean;\n      readonly cipher?: string;\n      readonly passphraseRef?: SecretRefString;\n    };\n  };\n  readonly audit: {\n    readonly enabled: boolean;\n    readonly path?: string;\n    readonly passphraseRef?: SecretRefString;\n    readonly cipher?: string;\n  };\n  readonly secrets: {\n    readonly source: SecretsSource;\n    readonly strict: boolean;\n  };\n  readonly auth: {\n    readonly kind: 'token' | 'none';\n    readonly pepperRef?: SecretRefString;\n    readonly tokenPrefix: string;\n    readonly tokenEnvironments: ReadonlyArray<string>;\n    readonly perIpFailureThreshold?: number;\n    readonly perIpLockoutMs?: number;\n  };\n  readonly observability: {\n    readonly logger: 'json' | 'pretty' | 'silent';\n  };\n  readonly hardening: {\n    readonly applyOnStart: boolean;\n    readonly refuseRoot: boolean;\n    readonly umask: number;\n  };\n  readonly metrics: {\n    readonly enabled: boolean;\n    readonly path: string;\n    readonly requireAuth: boolean;\n  };\n  readonly health: {\n    readonly walWarnThresholdBytes: number;\n  };\n}\n\nconst corsSchema = z\n  .object({\n    allowOrigins: z.array(z.string()).default([]),\n    allowCredentials: z.boolean().default(false),\n    allowMethods: z.array(z.string()).default(['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS']),\n    allowHeaders: z\n      .array(z.string())\n      .default(['Authorization', 'Content-Type', 'Idempotency-Key', 'X-CSRF-Token']),\n    maxAgeSeconds: z.number().int().nonnegative().default(600),\n  })\n  .strict()\n  .default({});\n\nconst csrfSchema = z\n  .object({\n    enabled: z.boolean().default(true),\n    cookieName: z.string().default('graphorin_csrf'),\n    headerName: z.string().default('X-CSRF-Token'),\n    safeMethods: z.array(z.string()).default(['GET', 'HEAD', 'OPTIONS']),\n  })\n  .strict()\n  .default({});\n\nconst rateLimitSchema = z\n  .object({\n    enabled: z.boolean().default(true),\n    windowMs: z.number().int().positive().default(60_000),\n    perIpRequests: z.number().int().positive().default(60),\n  })\n  .strict()\n  .default({});\n\nconst idempotencySchema = z\n  .object({\n    enabled: z.boolean().default(true),\n    requireKey: z.enum(['off', 'warn', 'enforce']).default('warn'),\n    ttlSeconds: z.number().int().positive().default(86_400),\n    checkBodyFingerprint: z.boolean().default(true),\n    lruCacheSize: z.number().int().positive().default(1_000),\n  })\n  .strict()\n  .default({});\n\nconst shutdownSchema = z\n  .object({\n    drainTimeoutMs: z.number().int().positive().default(30_000),\n  })\n  .strict()\n  .default({});\n\nconst streamReplayBufferSchema = z\n  .object({\n    maxEvents: z.number().int().positive().default(1_000),\n    ttlSeconds: z.number().int().positive().default(300),\n  })\n  .strict()\n  .default({});\n\nconst streamSchema = z\n  .object({\n    disconnectPolicy: z\n      .enum(['continue', 'pause-on-disconnect', 'abort-on-disconnect'])\n      .default('continue'),\n    disconnectGracePeriodMs: z.number().int().nonnegative().default(10_000),\n    replayBuffer: streamReplayBufferSchema,\n    perConnectionQueueLimit: z.number().int().positive().default(1_000),\n  })\n  .strict()\n  .default({});\n\nconst wsCommentarySchema = z\n  .object({\n    policy: z.enum(['wrap', 'strip', 'pass-through']).default('wrap'),\n    applyToEvents: z\n      .array(z.string().min(1))\n      .default(['tool.execute.end', 'tool.execute.error', 'text.delta']),\n  })\n  .strict()\n  .default({});\n\nconst wsSchema = z\n  .object({\n    enabled: z.boolean().default(true),\n    path: z.string().default('/ws'),\n    ticketTtlMs: z\n      .number()\n      .int()\n      .positive()\n      .default(5 * 60_000),\n    commentarySanitization: wsCommentarySchema,\n  })\n  .strict()\n  .default({});\n\nconst sseSchema = z\n  .object({\n    enabled: z.boolean().default(true),\n    path: z.string().default('/sessions'),\n    keepAliveMs: z.number().int().positive().default(15_000),\n  })\n  .strict()\n  .default({});\n\nconst serverSchema = z\n  .object({\n    host: z.string().min(1).default('127.0.0.1'),\n    port: z.number().int().min(0).max(65_535).default(8_080),\n    basePath: z.string().default('/v1'),\n    cors: corsSchema,\n    csrf: csrfSchema,\n    rateLimit: rateLimitSchema,\n    idempotency: idempotencySchema,\n    shutdown: shutdownSchema,\n    trustProxy: z.boolean().default(false),\n    stream: streamSchema,\n    ws: wsSchema,\n    sse: sseSchema,\n  })\n  .strict()\n  .default({});\n\nconst encryptionSchema = z\n  .object({\n    enabled: z.boolean().default(false),\n    cipher: z.string().optional(),\n    passphraseRef: z.string().optional(),\n  })\n  .strict()\n  .default({});\n\nconst storageSchema = z\n  .object({\n    path: z.string().min(1).default('./.graphorin/data.db'),\n    mode: z.enum(['lib', 'server']).default('server'),\n    walCheckpointIntervalMs: z.number().int().positive().optional(),\n    encryption: encryptionSchema,\n  })\n  .strict()\n  .default({});\n\nconst auditSchema = z\n  .object({\n    enabled: z.boolean().default(false),\n    path: z.string().optional(),\n    passphraseRef: z.string().optional(),\n    cipher: z.string().optional(),\n  })\n  .strict()\n  .default({});\n\nconst secretsSchema = z\n  .object({\n    source: z.enum(['auto', 'keyring', 'encrypted-file', 'env']).default('auto'),\n    strict: z.boolean().default(false),\n  })\n  .strict()\n  .default({});\n\nconst authSchema = z\n  .object({\n    kind: z.enum(['token', 'none']).default('token'),\n    pepperRef: z.string().optional(),\n    tokenPrefix: z.string().default('gph'),\n    tokenEnvironments: z.array(z.string()).default(['live', 'test', 'local']),\n    perIpFailureThreshold: z.number().int().positive().optional(),\n    perIpLockoutMs: z.number().int().positive().optional(),\n  })\n  .strict()\n  .default({});\n\nconst observabilitySchema = z\n  .object({\n    logger: z.enum(['json', 'pretty', 'silent']).default('json'),\n  })\n  .strict()\n  .default({});\n\nconst hardeningSchema = z\n  .object({\n    applyOnStart: z.boolean().default(true),\n    refuseRoot: z.boolean().default(true),\n    umask: z.number().int().nonnegative().default(0o077),\n  })\n  .strict()\n  .default({});\n\nconst metricsSchema = z\n  .object({\n    enabled: z.boolean().default(true),\n    path: z.string().default('/metrics'),\n    requireAuth: z.boolean().default(false),\n  })\n  .strict()\n  .default({});\n\nconst healthSchema = z\n  .object({\n    walWarnThresholdBytes: z\n      .number()\n      .int()\n      .positive()\n      .default(50 * 1024 * 1024),\n  })\n  .strict()\n  .default({});\n\n/**\n * Zod schema for the resolved {@link ServerConfigSpec}. Exposed for\n * advanced users that want to validate other config sources (env-only\n * launch, CLI overrides, etc.).\n *\n * @stable\n */\nexport const ServerConfigSchema = z\n  .object({\n    server: serverSchema,\n    storage: storageSchema,\n    audit: auditSchema,\n    secrets: secretsSchema,\n    auth: authSchema,\n    observability: observabilitySchema,\n    hardening: hardeningSchema,\n    metrics: metricsSchema,\n    health: healthSchema,\n  })\n  .strict()\n  .default({});\n\n/**\n * Input shape accepted by {@link defineConfig}. Every field is\n * optional; missing values fall back to a documented default.\n *\n * @stable\n */\nexport type ServerConfigInput = z.input<typeof ServerConfigSchema>;\n\n/**\n * Helper for `graphorin.config.ts` files. Pure pass-through that\n * provides editor autocomplete; the actual parsing happens at server\n * startup so callers always see the same error path regardless of\n * which loader (TS / JS / JSON) the operator picked.\n *\n * @stable\n */\nexport function defineConfig(input: ServerConfigInput): ServerConfigInput {\n  return input;\n}\n\n/**\n * Parse + validate user input. Returns a strongly-typed\n * {@link ServerConfigSpec}; throws {@link ConfigInvalidError} on\n * any invalid field with a flattened issue list.\n *\n * @stable\n */\nexport function parseServerConfig(input: unknown): ServerConfigSpec {\n  const result = ServerConfigSchema.safeParse(input ?? {});\n  if (!result.success) {\n    const issues = result.error.issues.map((issue) => ({\n      path: issue.path,\n      message: issue.message,\n    }));\n    throw new ConfigInvalidError(issues, result.error);\n  }\n  return result.data as unknown as ServerConfigSpec;\n}\n"],"mappings":"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"}

package/dist/consolidator/daemon.d.ts

@@ -0,0 +1,88 @@
+import * as _graphorin_triggers0 from "@graphorin/triggers";
+
+//#region src/consolidator/daemon.d.ts
+
+/**
+ * Lifecycle wrapper around an externally-built `Consolidator`. Phase
+ * 14c wires the runtime into `beforeStart` / `beforeShutdown` so the
+ * background pipeline starts and stops cleanly with the daemon. The
+ * adapter does not own the consolidator construction — operators
+ * supply the instance through the `createServer({ consolidator })`
+ * option so the framework stays decoupled from the heavy
+ * `@graphorin/memory` package.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Structurally-typed view of the `@graphorin/memory` Consolidator
+ * surface. Importing the full type would force a hard dependency on
+ * `@graphorin/memory`; the structural subset captured here is enough
+ * for the lifecycle integration + the `/v1/health` aggregator.
+ *
+ * @stable
+ */
+interface ConsolidatorLike {
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  status(): Promise<ConsolidatorStatusLike>;
+  setTier?(tier: string): Promise<void>;
+  pause?(): Promise<void>;
+  resume?(): Promise<void>;
+  drainDlq?(): Promise<number>;
+  /**
+   * Register the consolidator's cron / idle triggers with the server's
+   * triggers scheduler so background consolidation actually fires (MCON-4).
+   * Called from `beforeStart` when both a consolidator and a triggers daemon
+   * are configured. Optional so a consolidator without a `defaultScope` (or a
+   * custom surface) simply opts out.
+   */
+  registerWithScheduler?(scheduler: _graphorin_triggers0.Scheduler): Promise<unknown>;
+}
+/**
+ * Subset of `ConsolidatorStatus` the server health endpoint and the
+ * Prometheus metrics consume. The full struct lives in
+ * `@graphorin/memory/consolidator`.
+ *
+ * @stable
+ */
+interface ConsolidatorStatusLike {
+  readonly tier: string;
+  readonly running: boolean;
+  readonly paused: boolean;
+  readonly queueDepth: number;
+  readonly dlqSize: number;
+  readonly deferredRuns: number;
+  readonly emptyExtractions: number;
+  readonly budget: {
+    readonly tokensUsedToday: number;
+    readonly costUsedToday: number;
+    readonly tokensRemaining: number;
+    readonly costRemaining: number;
+    readonly resetAt: string;
+  };
+}
+/**
+ * @stable
+ */
+interface CreateConsolidatorDaemonOptions {
+  readonly consolidator: ConsolidatorLike;
+  /** Hard timeout on `consolidator.stop()`. Defaults to 10 s. */
+  readonly stopTimeoutMs?: number;
+  readonly warn?: (message: string) => void;
+}
+/**
+ * @stable
+ */
+interface ConsolidatorDaemon {
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  status(): Promise<ConsolidatorStatusLike>;
+  readonly consolidator: ConsolidatorLike;
+}
+/**
+ * @stable
+ */
+declare function createConsolidatorDaemon(options: CreateConsolidatorDaemonOptions): ConsolidatorDaemon;
+//#endregion
+export { ConsolidatorDaemon, ConsolidatorLike, ConsolidatorStatusLike, CreateConsolidatorDaemonOptions, createConsolidatorDaemon };
+//# sourceMappingURL=daemon.d.ts.map

package/dist/consolidator/daemon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemon.d.ts","names":[],"sources":["../../src/consolidator/daemon.ts"],"sourcesContent":[],"mappings":";;;;;;;AAoBA;;;;;;;;;;;;AAyBA;AAoBA;AAUA;;AAEU,UAzDO,gBAAA,CAyDP;EACU,KAAA,EAAA,EAzDT,OAyDS,CAAA,IAAA,CAAA;EAAR,IAAA,EAAA,EAxDF,OAwDE,CAAA,IAAA,CAAA;EACa,MAAA,EAAA,EAxDb,OAwDa,CAxDL,sBAwDK,CAAA;EAAgB,OAAA,EAAA,IAAA,EAAA,MAAA,CAAA,EAvDf,OAuDe,CAAA,IAAA,CAAA;EAMzB,KAAA,GAAA,EA5DJ,OA4DI,CAAA,IAAA,CAAA;aA3DH;eACE;;;;;;;;oCAAO,oBAAA,CAQ4C,YAAY;;;;;;;;;UAU7D,sBAAA;;;;;;;;;;;;;;;;;;;UAoBA,+BAAA;yBACQ;;;;;;;;UASR,kBAAA;WACN;UACD;YACE,QAAQ;yBACK;;;;;iBAMT,wBAAA,UACL,kCACR"}

package/dist/consolidator/daemon.js

@@ -0,0 +1,54 @@
+//#region src/consolidator/daemon.ts
+/**
+* @stable
+*/
+function createConsolidatorDaemon(options) {
+	const stopTimeoutMs = options.stopTimeoutMs ?? 1e4;
+	const warn = options.warn ?? ((m) => process.stderr.write(`${m}\n`));
+	let started = false;
+	return {
+		get consolidator() {
+			return options.consolidator;
+		},
+		async start() {
+			if (started) return;
+			started = true;
+			await options.consolidator.start();
+		},
+		async stop() {
+			if (!started) return;
+			started = false;
+			try {
+				await withTimeout(options.consolidator.stop(), stopTimeoutMs);
+			} catch (err) {
+				warn(`[graphorin/server] consolidator daemon: stop() exceeded ${stopTimeoutMs}ms; force-aborting (${describeError(err)}).`);
+			}
+		},
+		async status() {
+			return options.consolidator.status();
+		}
+	};
+}
+async function withTimeout(p, ms) {
+	return new Promise((resolve, reject) => {
+		const timer = setTimeout(() => {
+			reject(/* @__PURE__ */ new Error(`timeout after ${ms}ms`));
+		}, ms);
+		p.then((value) => {
+			clearTimeout(timer);
+			resolve(value);
+		}, (err) => {
+			clearTimeout(timer);
+			reject(err);
+		});
+	});
+}
+function describeError(err) {
+	if (err === null || err === void 0) return "unknown";
+	if (err instanceof Error) return err.message;
+	return String(err);
+}
+
+//#endregion
+export { createConsolidatorDaemon };
+//# sourceMappingURL=daemon.js.map

package/dist/consolidator/daemon.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemon.js","names":[],"sources":["../../src/consolidator/daemon.ts"],"sourcesContent":["/**\n * Lifecycle wrapper around an externally-built `Consolidator`. Phase\n * 14c wires the runtime into `beforeStart` / `beforeShutdown` so the\n * background pipeline starts and stops cleanly with the daemon. The\n * adapter does not own the consolidator construction — operators\n * supply the instance through the `createServer({ consolidator })`\n * option so the framework stays decoupled from the heavy\n * `@graphorin/memory` package.\n *\n * @packageDocumentation\n */\n\n/**\n * Structurally-typed view of the `@graphorin/memory` Consolidator\n * surface. Importing the full type would force a hard dependency on\n * `@graphorin/memory`; the structural subset captured here is enough\n * for the lifecycle integration + the `/v1/health` aggregator.\n *\n * @stable\n */\nexport interface ConsolidatorLike {\n  start(): Promise<void>;\n  stop(): Promise<void>;\n  status(): Promise<ConsolidatorStatusLike>;\n  setTier?(tier: string): Promise<void>;\n  pause?(): Promise<void>;\n  resume?(): Promise<void>;\n  drainDlq?(): Promise<number>;\n  /**\n   * Register the consolidator's cron / idle triggers with the server's\n   * triggers scheduler so background consolidation actually fires (MCON-4).\n   * Called from `beforeStart` when both a consolidator and a triggers daemon\n   * are configured. Optional so a consolidator without a `defaultScope` (or a\n   * custom surface) simply opts out.\n   */\n  registerWithScheduler?(scheduler: import('@graphorin/triggers').Scheduler): Promise<unknown>;\n}\n\n/**\n * Subset of `ConsolidatorStatus` the server health endpoint and the\n * Prometheus metrics consume. The full struct lives in\n * `@graphorin/memory/consolidator`.\n *\n * @stable\n */\nexport interface ConsolidatorStatusLike {\n  readonly tier: string;\n  readonly running: boolean;\n  readonly paused: boolean;\n  readonly queueDepth: number;\n  readonly dlqSize: number;\n  readonly deferredRuns: number;\n  readonly emptyExtractions: number;\n  readonly budget: {\n    readonly tokensUsedToday: number;\n    readonly costUsedToday: number;\n    readonly tokensRemaining: number;\n    readonly costRemaining: number;\n    readonly resetAt: string;\n  };\n}\n\n/**\n * @stable\n */\nexport interface CreateConsolidatorDaemonOptions {\n  readonly consolidator: ConsolidatorLike;\n  /** Hard timeout on `consolidator.stop()`. Defaults to 10 s. */\n  readonly stopTimeoutMs?: number;\n  readonly warn?: (message: string) => void;\n}\n\n/**\n * @stable\n */\nexport interface ConsolidatorDaemon {\n  start(): Promise<void>;\n  stop(): Promise<void>;\n  status(): Promise<ConsolidatorStatusLike>;\n  readonly consolidator: ConsolidatorLike;\n}\n\n/**\n * @stable\n */\nexport function createConsolidatorDaemon(\n  options: CreateConsolidatorDaemonOptions,\n): ConsolidatorDaemon {\n  const stopTimeoutMs = options.stopTimeoutMs ?? 10_000;\n  const warn = options.warn ?? ((m: string) => process.stderr.write(`${m}\\n`));\n  let started = false;\n\n  return {\n    get consolidator() {\n      return options.consolidator;\n    },\n    async start() {\n      if (started) return;\n      started = true;\n      await options.consolidator.start();\n    },\n    async stop() {\n      if (!started) return;\n      started = false;\n      try {\n        await withTimeout(options.consolidator.stop(), stopTimeoutMs);\n      } catch (err) {\n        warn(\n          `[graphorin/server] consolidator daemon: stop() exceeded ${stopTimeoutMs}ms; force-aborting (${describeError(err)}).`,\n        );\n      }\n    },\n    async status() {\n      return options.consolidator.status();\n    },\n  };\n}\n\nasync function withTimeout<T>(p: Promise<T>, ms: number): Promise<T> {\n  return new Promise<T>((resolve, reject) => {\n    const timer = setTimeout(() => {\n      reject(new Error(`timeout after ${ms}ms`));\n    }, ms);\n    p.then(\n      (value) => {\n        clearTimeout(timer);\n        resolve(value);\n      },\n      (err) => {\n        clearTimeout(timer);\n        reject(err);\n      },\n    );\n  });\n}\n\nfunction describeError(err: unknown): string {\n  if (err === null || err === undefined) return 'unknown';\n  if (err instanceof Error) return err.message;\n  return String(err);\n}\n"],"mappings":";;;;AAqFA,SAAgB,yBACd,SACoB;CACpB,MAAM,gBAAgB,QAAQ,iBAAiB;CAC/C,MAAM,OAAO,QAAQ,UAAU,MAAc,QAAQ,OAAO,MAAM,GAAG,EAAE,IAAI;CAC3E,IAAI,UAAU;AAEd,QAAO;EACL,IAAI,eAAe;AACjB,UAAO,QAAQ;;EAEjB,MAAM,QAAQ;AACZ,OAAI,QAAS;AACb,aAAU;AACV,SAAM,QAAQ,aAAa,OAAO;;EAEpC,MAAM,OAAO;AACX,OAAI,CAAC,QAAS;AACd,aAAU;AACV,OAAI;AACF,UAAM,YAAY,QAAQ,aAAa,MAAM,EAAE,cAAc;YACtD,KAAK;AACZ,SACE,2DAA2D,cAAc,sBAAsB,cAAc,IAAI,CAAC,IACnH;;;EAGL,MAAM,SAAS;AACb,UAAO,QAAQ,aAAa,QAAQ;;EAEvC;;AAGH,eAAe,YAAe,GAAe,IAAwB;AACnE,QAAO,IAAI,SAAY,SAAS,WAAW;EACzC,MAAM,QAAQ,iBAAiB;AAC7B,0BAAO,IAAI,MAAM,iBAAiB,GAAG,IAAI,CAAC;KACzC,GAAG;AACN,IAAE,MACC,UAAU;AACT,gBAAa,MAAM;AACnB,WAAQ,MAAM;MAEf,QAAQ;AACP,gBAAa,MAAM;AACnB,UAAO,IAAI;IAEd;GACD;;AAGJ,SAAS,cAAc,KAAsB;AAC3C,KAAI,QAAQ,QAAQ,QAAQ,OAAW,QAAO;AAC9C,KAAI,eAAe,MAAO,QAAO,IAAI;AACrC,QAAO,OAAO,IAAI"}

package/dist/consolidator/index.d.ts

@@ -0,0 +1,2 @@
+import { ConsolidatorDaemon, ConsolidatorLike, ConsolidatorStatusLike, CreateConsolidatorDaemonOptions, createConsolidatorDaemon } from "./daemon.js";
+export { type ConsolidatorDaemon, type ConsolidatorLike, type ConsolidatorStatusLike, type CreateConsolidatorDaemonOptions, createConsolidatorDaemon };

package/dist/consolidator/index.js

@@ -0,0 +1,3 @@
+import { createConsolidatorDaemon } from "./daemon.js";
+
+export { createConsolidatorDaemon };

package/dist/errors/index.d.ts

@@ -0,0 +1,104 @@
+//#region src/errors/index.d.ts
+/**
+ * Typed error surface for `@graphorin/server`. Every server-side
+ * configuration / lifecycle / runtime failure that an operator must
+ * be able to reason about flows through one of the classes in this
+ * module so it carries a stable `kind` discriminator + `hint` field
+ * pointing the operator at the next remediation step.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Stable string discriminator for {@link GraphorinServerError}. Each
+ * value maps to a single failure scenario; never reuse a value for a
+ * different cause.
+ *
+ * @stable
+ */
+type GraphorinServerErrorCode = 'config-invalid' | 'pre-bind-pepper-missing' | 'pre-bind-secret-unresolvable' | 'pre-bind-encryption-peer-missing' | 'pre-bind-encryption-required' | 'migration-failed' | 'shutdown-timeout' | 'idempotency-conflict' | 'idempotency-key-required' | 'auth-required' | 'auth-invalid' | 'auth-revoked' | 'auth-expired' | 'auth-locked-out' | 'auth-overloaded' | 'scope-denied' | 'csrf-denied' | 'cors-denied' | 'rate-limit-exceeded' | 'route-handler-missing' | 'agent-not-found' | 'workflow-not-found' | 'session-not-found' | 'run-not-found' | 'run-aborted' | 'lifecycle-double-start' | 'lifecycle-not-started';
+/**
+ * Base error class. Every server-emitted typed error inherits from
+ * here so middleware can pattern-match a single union.
+ *
+ * @stable
+ */
+declare class GraphorinServerError extends Error {
+  readonly kind: GraphorinServerErrorCode;
+  readonly hint?: string;
+  constructor(kind: GraphorinServerErrorCode, message: string, options?: {
+    readonly cause?: unknown;
+    readonly hint?: string;
+  });
+}
+/** @stable */
+declare class ConfigInvalidError extends GraphorinServerError {
+  readonly issues: ReadonlyArray<{
+    readonly path: ReadonlyArray<string | number>;
+    readonly message: string;
+  }>;
+  constructor(issues: ReadonlyArray<{
+    readonly path: ReadonlyArray<string | number>;
+    readonly message: string;
+  }>, cause?: unknown);
+}
+/** @stable */
+declare class PrebindPepperMissingError extends GraphorinServerError {
+  constructor();
+}
+/** @stable */
+declare class PrebindSecretUnresolvableError extends GraphorinServerError {
+  readonly path: ReadonlyArray<string | number>;
+  readonly raw: string;
+  constructor(path: ReadonlyArray<string | number>, raw: string, cause?: unknown);
+}
+/** @stable */
+declare class PrebindEncryptionPeerMissingError extends GraphorinServerError {
+  constructor(cause?: unknown);
+}
+/** @stable */
+declare class PrebindEncryptionRequiredError extends GraphorinServerError {
+  constructor(reason: string);
+}
+/** @stable */
+declare class MigrationFailedError extends GraphorinServerError {
+  constructor(message: string, cause?: unknown);
+}
+/** @stable */
+declare class ShutdownTimeoutError extends GraphorinServerError {
+  readonly drainTimeoutMs: number;
+  readonly inflight: number;
+  constructor(drainTimeoutMs: number, inflight: number);
+}
+/** @stable */
+declare class IdempotencyConflictError extends GraphorinServerError {
+  constructor(key: string);
+}
+/** @stable */
+declare class IdempotencyKeyRequiredError extends GraphorinServerError {
+  constructor();
+}
+/** @stable */
+declare class LifecycleDoubleStartError extends GraphorinServerError {
+  constructor();
+}
+/** @stable */
+declare class LifecycleNotStartedError extends GraphorinServerError {
+  constructor();
+}
+/** @stable */
+declare class RouteHandlerMissingError extends GraphorinServerError {
+  readonly id: string;
+  readonly kind_: 'agent' | 'workflow';
+  constructor(kind: 'agent' | 'workflow', id: string);
+}
+/** @stable */
+declare class AgentNotFoundError extends RouteHandlerMissingError {
+  constructor(id: string);
+}
+/** @stable */
+declare class WorkflowNotFoundError extends RouteHandlerMissingError {
+  constructor(id: string);
+}
+//#endregion
+export { AgentNotFoundError, ConfigInvalidError, GraphorinServerError, GraphorinServerErrorCode, IdempotencyConflictError, IdempotencyKeyRequiredError, LifecycleDoubleStartError, LifecycleNotStartedError, MigrationFailedError, PrebindEncryptionPeerMissingError, PrebindEncryptionRequiredError, PrebindPepperMissingError, PrebindSecretUnresolvableError, RouteHandlerMissingError, ShutdownTimeoutError, WorkflowNotFoundError };
+//# sourceMappingURL=index.d.ts.map

package/dist/errors/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/errors/index.ts"],"sourcesContent":[],"mappings":";;AAiBA;AAmCA;;;;;AAoBA;;;;;;;AAsBA;AAaA;AACiB,KA3FL,wBAAA,GA2FK,gBAAA,GAAA,yBAAA,GAAA,8BAAA,GAAA,kCAAA,GAAA,8BAAA,GAAA,kBAAA,GAAA,kBAAA,GAAA,sBAAA,GAAA,0BAAA,GAAA,eAAA,GAAA,cAAA,GAAA,cAAA,GAAA,cAAA,GAAA,iBAAA,GAAA,iBAAA,GAAA,cAAA,GAAA,aAAA,GAAA,aAAA,GAAA,qBAAA,GAAA,uBAAA,GAAA,iBAAA,GAAA,oBAAA,GAAA,mBAAA,GAAA,eAAA,GAAA,aAAA,GAAA,wBAAA,GAAA,uBAAA;;;;AAkBjB;AAcA;AASA;AAUa,cA3GA,oBAAA,SAA6B,KAAA,CA2GA;EAkB7B,SAAA,IAAA,EA5HI,wBA4H6B;EAajC,SAAA,IAAA,CAAA,EAAA,MAAA;EAaA,WAAA,CAAA,IAAA,EAlJH,wBAkJqC,EAAA,OAAA,EAAA,MAAA,EAAoB,OAgCtD,CAhCsD,EAAA;IAStD,SAAA,KAAA,CAAA,EAAA,OAAyB;IASzB,SAAA,IAAA,CAAA,EAAA,MAAA;EAcA,CAAA;AAOb;;cA1Ka,kBAAA,SAA2B,oBAAA;mBACrB;mBACA;;;sBAKP;mBACS;;;;;cAcR,yBAAA,SAAkC,oBAAA;;;;cAalC,8BAAA,SAAuC,oBAAA;iBACnC;;oBAGG;;;cAeP,iCAAA,SAA0C,oBAAA;;;;cAc1C,8BAAA,SAAuC,oBAAA;;;;cASvC,oBAAA,SAA6B,oBAAA;;;;cAU7B,oBAAA,SAA6B,oBAAA;;;;;;cAkB7B,wBAAA,SAAiC,oBAAA;;;;cAajC,2BAAA,SAAoC,oBAAA;;;;cAapC,yBAAA,SAAkC,oBAAA;;;;cASlC,wBAAA,SAAiC,oBAAA;;;;cASjC,wBAAA,SAAiC,oBAAA;;;;;;cAcjC,kBAAA,SAA2B,wBAAA;;;;cAO3B,qBAAA,SAA8B,wBAAA"}

package/dist/errors/index.js

@@ -0,0 +1,131 @@
+//#region src/errors/index.ts
+/**
+* Base error class. Every server-emitted typed error inherits from
+* here so middleware can pattern-match a single union.
+*
+* @stable
+*/
+var GraphorinServerError = class extends Error {
+	kind;
+	hint;
+	constructor(kind, message, options) {
+		super(message, options !== void 0 && options.cause !== void 0 ? { cause: options.cause } : void 0);
+		this.name = this.constructor.name;
+		this.kind = kind;
+		if (options?.hint !== void 0) this.hint = options.hint;
+	}
+};
+/** @stable */
+var ConfigInvalidError = class extends GraphorinServerError {
+	issues;
+	constructor(issues, cause) {
+		super("config-invalid", `graphorin.config invalid: ${issues.length} issue(s)`, {
+			hint: "Inspect the issues array; each entry pinpoints the offending path.",
+			...cause !== void 0 ? { cause } : {}
+		});
+		this.issues = Object.freeze(issues.slice());
+	}
+};
+/** @stable */
+var PrebindPepperMissingError = class extends GraphorinServerError {
+	constructor() {
+		super("pre-bind-pepper-missing", "auth.pepper SecretRef did not resolve to a non-empty pepper.", { hint: "Run `graphorin doctor --check-secrets` (Phase 15) and verify the configured SecretRef." });
+	}
+};
+/** @stable */
+var PrebindSecretUnresolvableError = class extends GraphorinServerError {
+	path;
+	raw;
+	constructor(path, raw, cause) {
+		super("pre-bind-secret-unresolvable", `Could not resolve SecretRef '${raw}' at config path ${path.join(".")}`, {
+			hint: "Run `graphorin doctor --check-secrets` (Phase 15) and verify the configured SecretRef.",
+			...cause !== void 0 ? { cause } : {}
+		});
+		this.path = Object.freeze(path.slice());
+		this.raw = raw;
+	}
+};
+/** @stable */
+var PrebindEncryptionPeerMissingError = class extends GraphorinServerError {
+	constructor(cause) {
+		super("pre-bind-encryption-peer-missing", "storage.encryption.enabled = true but the cipher peer is not installed.", {
+			hint: "Install the 'better-sqlite3-multiple-ciphers' peer (or set storage.encryption.enabled = false).",
+			...cause !== void 0 ? { cause } : {}
+		});
+	}
+};
+/** @stable */
+var PrebindEncryptionRequiredError = class extends GraphorinServerError {
+	constructor(reason) {
+		super("pre-bind-encryption-required", reason, { hint: "Audit logs are mandatory-encrypted (DEC-124); enable storage.encryption or supply audit.encryption explicitly." });
+	}
+};
+/** @stable */
+var MigrationFailedError = class extends GraphorinServerError {
+	constructor(message, cause) {
+		super("migration-failed", message, {
+			hint: "Inspect the underlying SQLite error and re-run `graphorin migrate`.",
+			...cause !== void 0 ? { cause } : {}
+		});
+	}
+};
+/** @stable */
+var ShutdownTimeoutError = class extends GraphorinServerError {
+	drainTimeoutMs;
+	inflight;
+	constructor(drainTimeoutMs, inflight) {
+		super("shutdown-timeout", `Drain timed out after ${drainTimeoutMs}ms with ${inflight} request(s) still in flight.`, { hint: "Increase server.shutdown.drainTimeoutMs or fix slow handlers." });
+		this.drainTimeoutMs = drainTimeoutMs;
+		this.inflight = inflight;
+	}
+};
+/** @stable */
+var IdempotencyConflictError = class extends GraphorinServerError {
+	constructor(key) {
+		super("idempotency-conflict", `Idempotency-Key '${key}' was previously used with a different request body.`, { hint: "Generate a fresh Idempotency-Key for the new payload." });
+	}
+};
+/** @stable */
+var IdempotencyKeyRequiredError = class extends GraphorinServerError {
+	constructor() {
+		super("idempotency-key-required", "Side-effecting endpoint requires an Idempotency-Key header.", { hint: "Set 'Idempotency-Key: <uuid>' on the request, or relax server.idempotency.requireKey to 'warn'." });
+	}
+};
+/** @stable */
+var LifecycleDoubleStartError = class extends GraphorinServerError {
+	constructor() {
+		super("lifecycle-double-start", "Server.start() invoked while the server is already started.", { hint: "Call stop() before re-starting the server." });
+	}
+};
+/** @stable */
+var LifecycleNotStartedError = class extends GraphorinServerError {
+	constructor() {
+		super("lifecycle-not-started", "Server.stop() invoked before start() resolved.", { hint: "Await start() before calling stop()." });
+	}
+};
+/** @stable */
+var RouteHandlerMissingError = class extends GraphorinServerError {
+	id;
+	kind_;
+	constructor(kind, id) {
+		super("route-handler-missing", `No ${kind} registered with id '${id}'.`, { hint: `Register the ${kind} via createServer({ ${kind}s: { ... } }) or the AgentRegistry / WorkflowRegistry surface.` });
+		this.id = id;
+		this.kind_ = kind;
+	}
+};
+/** @stable */
+var AgentNotFoundError = class extends RouteHandlerMissingError {
+	constructor(id) {
+		super("agent", id);
+	}
+};
+/** @stable */
+var WorkflowNotFoundError = class extends RouteHandlerMissingError {
+	constructor(id) {
+		super("workflow", id);
+	}
+};
+
+//#endregion
+export { AgentNotFoundError, ConfigInvalidError, GraphorinServerError, IdempotencyConflictError, IdempotencyKeyRequiredError, LifecycleDoubleStartError, LifecycleNotStartedError, MigrationFailedError, PrebindEncryptionPeerMissingError, PrebindEncryptionRequiredError, PrebindPepperMissingError, PrebindSecretUnresolvableError, RouteHandlerMissingError, ShutdownTimeoutError, WorkflowNotFoundError };
+//# sourceMappingURL=index.js.map