@graphorin/server 0.5.0

package/dist/errors/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/errors/index.ts"],"sourcesContent":["/**\n * Typed error surface for `@graphorin/server`. Every server-side\n * configuration / lifecycle / runtime failure that an operator must\n * be able to reason about flows through one of the classes in this\n * module so it carries a stable `kind` discriminator + `hint` field\n * pointing the operator at the next remediation step.\n *\n * @packageDocumentation\n */\n\n/**\n * Stable string discriminator for {@link GraphorinServerError}. Each\n * value maps to a single failure scenario; never reuse a value for a\n * different cause.\n *\n * @stable\n */\nexport type GraphorinServerErrorCode =\n  | 'config-invalid'\n  | 'pre-bind-pepper-missing'\n  | 'pre-bind-secret-unresolvable'\n  | 'pre-bind-encryption-peer-missing'\n  | 'pre-bind-encryption-required'\n  | 'migration-failed'\n  | 'shutdown-timeout'\n  | 'idempotency-conflict'\n  | 'idempotency-key-required'\n  | 'auth-required'\n  | 'auth-invalid'\n  | 'auth-revoked'\n  | 'auth-expired'\n  | 'auth-locked-out'\n  | 'auth-overloaded'\n  | 'scope-denied'\n  | 'csrf-denied'\n  | 'cors-denied'\n  | 'rate-limit-exceeded'\n  | 'route-handler-missing'\n  | 'agent-not-found'\n  | 'workflow-not-found'\n  | 'session-not-found'\n  | 'run-not-found'\n  | 'run-aborted'\n  | 'lifecycle-double-start'\n  | 'lifecycle-not-started';\n\n/**\n * Base error class. Every server-emitted typed error inherits from\n * here so middleware can pattern-match a single union.\n *\n * @stable\n */\nexport class GraphorinServerError extends Error {\n  readonly kind: GraphorinServerErrorCode;\n  readonly hint?: string;\n\n  constructor(\n    kind: GraphorinServerErrorCode,\n    message: string,\n    options?: { readonly cause?: unknown; readonly hint?: string },\n  ) {\n    super(\n      message,\n      options !== undefined && options.cause !== undefined ? { cause: options.cause } : undefined,\n    );\n    this.name = this.constructor.name;\n    this.kind = kind;\n    if (options?.hint !== undefined) this.hint = options.hint;\n  }\n}\n\n/** @stable */\nexport class ConfigInvalidError extends GraphorinServerError {\n  readonly issues: ReadonlyArray<{\n    readonly path: ReadonlyArray<string | number>;\n    readonly message: string;\n  }>;\n\n  constructor(\n    issues: ReadonlyArray<{\n      readonly path: ReadonlyArray<string | number>;\n      readonly message: string;\n    }>,\n    cause?: unknown,\n  ) {\n    super('config-invalid', `graphorin.config invalid: ${issues.length} issue(s)`, {\n      hint: 'Inspect the issues array; each entry pinpoints the offending path.',\n      ...(cause !== undefined ? { cause } : {}),\n    });\n    this.issues = Object.freeze(issues.slice());\n  }\n}\n\n/** @stable */\nexport class PrebindPepperMissingError extends GraphorinServerError {\n  constructor() {\n    super(\n      'pre-bind-pepper-missing',\n      'auth.pepper SecretRef did not resolve to a non-empty pepper.',\n      {\n        hint: 'Run `graphorin doctor --check-secrets` (Phase 15) and verify the configured SecretRef.',\n      },\n    );\n  }\n}\n\n/** @stable */\nexport class PrebindSecretUnresolvableError extends GraphorinServerError {\n  readonly path: ReadonlyArray<string | number>;\n  readonly raw: string;\n\n  constructor(path: ReadonlyArray<string | number>, raw: string, cause?: unknown) {\n    super(\n      'pre-bind-secret-unresolvable',\n      `Could not resolve SecretRef '${raw}' at config path ${path.join('.')}`,\n      {\n        hint: 'Run `graphorin doctor --check-secrets` (Phase 15) and verify the configured SecretRef.',\n        ...(cause !== undefined ? { cause } : {}),\n      },\n    );\n    this.path = Object.freeze(path.slice());\n    this.raw = raw;\n  }\n}\n\n/** @stable */\nexport class PrebindEncryptionPeerMissingError extends GraphorinServerError {\n  constructor(cause?: unknown) {\n    super(\n      'pre-bind-encryption-peer-missing',\n      'storage.encryption.enabled = true but the cipher peer is not installed.',\n      {\n        hint: \"Install the 'better-sqlite3-multiple-ciphers' peer (or set storage.encryption.enabled = false).\",\n        ...(cause !== undefined ? { cause } : {}),\n      },\n    );\n  }\n}\n\n/** @stable */\nexport class PrebindEncryptionRequiredError extends GraphorinServerError {\n  constructor(reason: string) {\n    super('pre-bind-encryption-required', reason, {\n      hint: 'Audit logs are mandatory-encrypted (DEC-124); enable storage.encryption or supply audit.encryption explicitly.',\n    });\n  }\n}\n\n/** @stable */\nexport class MigrationFailedError extends GraphorinServerError {\n  constructor(message: string, cause?: unknown) {\n    super('migration-failed', message, {\n      hint: 'Inspect the underlying SQLite error and re-run `graphorin migrate`.',\n      ...(cause !== undefined ? { cause } : {}),\n    });\n  }\n}\n\n/** @stable */\nexport class ShutdownTimeoutError extends GraphorinServerError {\n  readonly drainTimeoutMs: number;\n  readonly inflight: number;\n\n  constructor(drainTimeoutMs: number, inflight: number) {\n    super(\n      'shutdown-timeout',\n      `Drain timed out after ${drainTimeoutMs}ms with ${inflight} request(s) still in flight.`,\n      {\n        hint: 'Increase server.shutdown.drainTimeoutMs or fix slow handlers.',\n      },\n    );\n    this.drainTimeoutMs = drainTimeoutMs;\n    this.inflight = inflight;\n  }\n}\n\n/** @stable */\nexport class IdempotencyConflictError extends GraphorinServerError {\n  constructor(key: string) {\n    super(\n      'idempotency-conflict',\n      `Idempotency-Key '${key}' was previously used with a different request body.`,\n      {\n        hint: 'Generate a fresh Idempotency-Key for the new payload.',\n      },\n    );\n  }\n}\n\n/** @stable */\nexport class IdempotencyKeyRequiredError extends GraphorinServerError {\n  constructor() {\n    super(\n      'idempotency-key-required',\n      'Side-effecting endpoint requires an Idempotency-Key header.',\n      {\n        hint: \"Set 'Idempotency-Key: <uuid>' on the request, or relax server.idempotency.requireKey to 'warn'.\",\n      },\n    );\n  }\n}\n\n/** @stable */\nexport class LifecycleDoubleStartError extends GraphorinServerError {\n  constructor() {\n    super('lifecycle-double-start', 'Server.start() invoked while the server is already started.', {\n      hint: 'Call stop() before re-starting the server.',\n    });\n  }\n}\n\n/** @stable */\nexport class LifecycleNotStartedError extends GraphorinServerError {\n  constructor() {\n    super('lifecycle-not-started', 'Server.stop() invoked before start() resolved.', {\n      hint: 'Await start() before calling stop().',\n    });\n  }\n}\n\n/** @stable */\nexport class RouteHandlerMissingError extends GraphorinServerError {\n  readonly id: string;\n  readonly kind_: 'agent' | 'workflow';\n\n  constructor(kind: 'agent' | 'workflow', id: string) {\n    super('route-handler-missing', `No ${kind} registered with id '${id}'.`, {\n      hint: `Register the ${kind} via createServer({ ${kind}s: { ... } }) or the AgentRegistry / WorkflowRegistry surface.`,\n    });\n    this.id = id;\n    this.kind_ = kind;\n  }\n}\n\n/** @stable */\nexport class AgentNotFoundError extends RouteHandlerMissingError {\n  constructor(id: string) {\n    super('agent', id);\n  }\n}\n\n/** @stable */\nexport class WorkflowNotFoundError extends RouteHandlerMissingError {\n  constructor(id: string) {\n    super('workflow', id);\n  }\n}\n"],"mappings":";;;;;;;AAoDA,IAAa,uBAAb,cAA0C,MAAM;CAC9C,AAAS;CACT,AAAS;CAET,YACE,MACA,SACA,SACA;AACA,QACE,SACA,YAAY,UAAa,QAAQ,UAAU,SAAY,EAAE,OAAO,QAAQ,OAAO,GAAG,OACnF;AACD,OAAK,OAAO,KAAK,YAAY;AAC7B,OAAK,OAAO;AACZ,MAAI,SAAS,SAAS,OAAW,MAAK,OAAO,QAAQ;;;;AAKzD,IAAa,qBAAb,cAAwC,qBAAqB;CAC3D,AAAS;CAKT,YACE,QAIA,OACA;AACA,QAAM,kBAAkB,6BAA6B,OAAO,OAAO,YAAY;GAC7E,MAAM;GACN,GAAI,UAAU,SAAY,EAAE,OAAO,GAAG,EAAE;GACzC,CAAC;AACF,OAAK,SAAS,OAAO,OAAO,OAAO,OAAO,CAAC;;;;AAK/C,IAAa,4BAAb,cAA+C,qBAAqB;CAClE,cAAc;AACZ,QACE,2BACA,gEACA,EACE,MAAM,0FACP,CACF;;;;AAKL,IAAa,iCAAb,cAAoD,qBAAqB;CACvE,AAAS;CACT,AAAS;CAET,YAAY,MAAsC,KAAa,OAAiB;AAC9E,QACE,gCACA,gCAAgC,IAAI,mBAAmB,KAAK,KAAK,IAAI,IACrE;GACE,MAAM;GACN,GAAI,UAAU,SAAY,EAAE,OAAO,GAAG,EAAE;GACzC,CACF;AACD,OAAK,OAAO,OAAO,OAAO,KAAK,OAAO,CAAC;AACvC,OAAK,MAAM;;;;AAKf,IAAa,oCAAb,cAAuD,qBAAqB;CAC1E,YAAY,OAAiB;AAC3B,QACE,oCACA,2EACA;GACE,MAAM;GACN,GAAI,UAAU,SAAY,EAAE,OAAO,GAAG,EAAE;GACzC,CACF;;;;AAKL,IAAa,iCAAb,cAAoD,qBAAqB;CACvE,YAAY,QAAgB;AAC1B,QAAM,gCAAgC,QAAQ,EAC5C,MAAM,kHACP,CAAC;;;;AAKN,IAAa,uBAAb,cAA0C,qBAAqB;CAC7D,YAAY,SAAiB,OAAiB;AAC5C,QAAM,oBAAoB,SAAS;GACjC,MAAM;GACN,GAAI,UAAU,SAAY,EAAE,OAAO,GAAG,EAAE;GACzC,CAAC;;;;AAKN,IAAa,uBAAb,cAA0C,qBAAqB;CAC7D,AAAS;CACT,AAAS;CAET,YAAY,gBAAwB,UAAkB;AACpD,QACE,oBACA,yBAAyB,eAAe,UAAU,SAAS,+BAC3D,EACE,MAAM,iEACP,CACF;AACD,OAAK,iBAAiB;AACtB,OAAK,WAAW;;;;AAKpB,IAAa,2BAAb,cAA8C,qBAAqB;CACjE,YAAY,KAAa;AACvB,QACE,wBACA,oBAAoB,IAAI,uDACxB,EACE,MAAM,yDACP,CACF;;;;AAKL,IAAa,8BAAb,cAAiD,qBAAqB;CACpE,cAAc;AACZ,QACE,4BACA,+DACA,EACE,MAAM,mGACP,CACF;;;;AAKL,IAAa,4BAAb,cAA+C,qBAAqB;CAClE,cAAc;AACZ,QAAM,0BAA0B,+DAA+D,EAC7F,MAAM,8CACP,CAAC;;;;AAKN,IAAa,2BAAb,cAA8C,qBAAqB;CACjE,cAAc;AACZ,QAAM,yBAAyB,kDAAkD,EAC/E,MAAM,wCACP,CAAC;;;;AAKN,IAAa,2BAAb,cAA8C,qBAAqB;CACjE,AAAS;CACT,AAAS;CAET,YAAY,MAA4B,IAAY;AAClD,QAAM,yBAAyB,MAAM,KAAK,uBAAuB,GAAG,KAAK,EACvE,MAAM,gBAAgB,KAAK,sBAAsB,KAAK,iEACvD,CAAC;AACF,OAAK,KAAK;AACV,OAAK,QAAQ;;;;AAKjB,IAAa,qBAAb,cAAwC,yBAAyB;CAC/D,YAAY,IAAY;AACtB,QAAM,SAAS,GAAG;;;;AAKtB,IAAa,wBAAb,cAA2C,yBAAyB;CAClE,YAAY,IAAY;AACtB,QAAM,YAAY,GAAG"}

package/dist/health/checks.d.ts

@@ -0,0 +1,120 @@
+import { ConsolidatorDaemon } from "../consolidator/daemon.js";
+import { TriggersDaemon } from "../triggers/daemon.js";
+import { GraphorinSqliteStore } from "@graphorin/store-sqlite";
+
+//#region src/health/checks.d.ts
+
+/** @stable */
+interface ReplayBufferProbe {
+  /** Total events buffered across all subjects. Aggregated by the caller. */
+  readonly eventsBuffered: number;
+  readonly subscribers?: number;
+  readonly subscriptions?: number;
+}
+/** @stable */
+type HealthStatus = 'ok' | 'warn' | 'fail';
+/** @stable */
+type HealthRollup = 'ok' | 'degraded' | 'failing';
+/**
+ * Common discriminator carried on every per-subsystem check entry.
+ * Concrete shapes extend this with subsystem-specific fields per the
+ * documented contract.
+ *
+ * @stable
+ */
+interface BaseHealthCheck {
+  readonly status: HealthStatus;
+  readonly message?: string;
+}
+/** @stable */
+interface StorageCheck extends BaseHealthCheck {
+  readonly walSizeBytes: number;
+  readonly warnThresholdBytes: number;
+  readonly lastCheckpointAt?: string;
+}
+/** @stable */
+interface EmbedderCheck extends BaseHealthCheck {
+  readonly modelLoaded: boolean;
+  readonly model?: string;
+}
+/** @stable */
+interface SecretsCheck extends BaseHealthCheck {
+  readonly activeStore: string;
+}
+/** @stable */
+interface EncryptionCheck extends BaseHealthCheck {
+  readonly enabled: boolean;
+  readonly peerDepInstalled: boolean;
+}
+/** @stable */
+interface ConsolidatorCheck extends BaseHealthCheck {
+  readonly tier: string;
+  readonly running: boolean;
+  readonly paused: boolean;
+  readonly queueDepth: number;
+  readonly dlqSize: number;
+  readonly budgetRemaining: {
+    readonly tokens: number;
+    readonly costUsd: number;
+  };
+}
+/** @stable */
+interface TriggersCheck extends BaseHealthCheck {
+  readonly running: boolean;
+  readonly active: number;
+  readonly disabled: number;
+  readonly deferred: number;
+  readonly lastFireAt?: string;
+}
+/** @stable */
+interface ReplayBufferCheck extends BaseHealthCheck {
+  readonly eventsBuffered: number;
+  readonly subscribers?: number;
+  readonly subscriptions?: number;
+}
+/** @stable */
+type HealthCheck = StorageCheck | EmbedderCheck | SecretsCheck | EncryptionCheck | ConsolidatorCheck | TriggersCheck | ReplayBufferCheck;
+/** @stable */
+interface HealthChecks {
+  readonly storage?: StorageCheck;
+  readonly embedder?: EmbedderCheck;
+  readonly secrets?: SecretsCheck;
+  readonly encryption?: EncryptionCheck;
+  readonly consolidator?: ConsolidatorCheck;
+  readonly triggers?: TriggersCheck;
+  readonly replayBuffer?: ReplayBufferCheck;
+}
+/** @stable */
+interface HealthSummary {
+  readonly status: HealthRollup;
+  readonly checks: HealthChecks;
+}
+/** @stable */
+interface HealthCheckOptions {
+  readonly store?: GraphorinSqliteStore;
+  readonly triggers?: TriggersDaemon;
+  readonly consolidator?: ConsolidatorDaemon;
+  readonly replayBuffer?: ReplayBufferProbe;
+  readonly secretsActive?: string;
+  readonly encryptionEnabled?: boolean;
+  readonly cipherPeerInstalled?: boolean;
+  readonly embedderModel?: string;
+  readonly embedderLoaded?: boolean;
+  /** Highest acceptable WAL size in bytes before warning. Default 50 MB. */
+  readonly walWarnThresholdBytes?: number;
+}
+/**
+ * Build the aggregate health summary from runtime probes.
+ *
+ * @stable
+ */
+declare function collectHealth(options: HealthCheckOptions): Promise<HealthSummary>;
+/**
+ * Promote the worst per-check status to the rollup label.
+ *
+ * @stable
+ */
+declare function rollup(checks: HealthChecks): HealthRollup;
+//#endregion
+export { BaseHealthCheck, ConsolidatorCheck, EmbedderCheck, EncryptionCheck, HealthCheck, HealthCheckOptions, HealthChecks, HealthRollup, HealthStatus, HealthSummary, ReplayBufferCheck, ReplayBufferProbe, SecretsCheck, StorageCheck, TriggersCheck, collectHealth, rollup };
+//# sourceMappingURL=checks.d.ts.map

package/dist/health/checks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checks.d.ts","names":[],"sources":["../../src/health/checks.ts"],"sourcesContent":[],"mappings":";;;;;;AA2FA;AAOY,UA/EK,iBAAA,CA+EM;EACnB;EACA,SAAA,cAAA,EAAA,MAAA;EACA,SAAA,WAAA,CAAA,EAAA,MAAA;EACA,SAAA,aAAA,CAAA,EAAA,MAAA;;;AAGA,KA9EQ,YAAA,GA8ER,IAAA,GAAA,MAAA,GAAA,MAAA;;AAGa,KA9EL,YAAA,GA8EiB,IAAA,GAAA,UAAA,GAAA,SAAA;;;;;;;;AAOc,UA5E1B,eAAA,CA4E0B;EAI1B,SAAA,MAAA,EA/EE,YAgFA;EAKF,SAAA,OAAA,CAAA,EAAA,MAAkB;;;AAGT,UAnFT,YAAA,SAAqB,eAmFZ,CAAA;EACA,SAAA,YAAA,EAAA,MAAA;EAAiB,SAAA,kBAAA,EAAA,MAAA;EAiBrB,SAAA,gBAAa,CAAA,EAAA,MAAA;;;AAA+B,UA9FjD,aAAA,SAAsB,eA8F2B,CAAA;EAAO,SAAA,WAAA,EAAA,OAAA;EAuHzD,SAAM,KAAA,CAAA,EAAA,MAAS;;;UA/Md,YAAA,SAAqB;;;;UAKrB,eAAA,SAAwB;;;;;UAMxB,iBAAA,SAA0B;;;;;;;;;;;;UAa1B,aAAA,SAAsB;;;;;;;;UAStB,iBAAA,SAA0B;;;;;;KAO/B,WAAA,GACR,eACA,gBACA,eACA,kBACA,oBACA,gBACA;;UAGa,YAAA;qBACI;sBACC;qBACD;wBACG;0BACE;sBACJ;0BACI;;;UAIT,aAAA;mBACE;mBACA;;;UAIF,kBAAA;mBACE;sBACG;0BACI;0BACA;;;;;;;;;;;;;;iBAiBJ,aAAA,UAAuB,qBAAqB,QAAQ;;;;;;iBAuH1D,MAAA,SAAe,eAAe"}

package/dist/health/checks.js

@@ -0,0 +1,127 @@
+import { readWalSize } from "@graphorin/store-sqlite";
+
+//#region src/health/checks.ts
+const DEFAULT_WAL_WARN_THRESHOLD_BYTES = 50 * 1024 * 1024;
+/**
+* Build the aggregate health summary from runtime probes.
+*
+* @stable
+*/
+async function collectHealth(options) {
+	const checks = {};
+	if (options.store !== void 0) {
+		const walSize = readWalSizeSafely(options.store);
+		const threshold = options.walWarnThresholdBytes ?? DEFAULT_WAL_WARN_THRESHOLD_BYTES;
+		checks.storage = {
+			status: walSize > threshold ? "warn" : "ok",
+			walSizeBytes: walSize,
+			warnThresholdBytes: threshold
+		};
+	}
+	if (options.embedderLoaded !== void 0) checks.embedder = {
+		status: options.embedderLoaded ? "ok" : "warn",
+		modelLoaded: options.embedderLoaded,
+		...options.embedderModel !== void 0 ? { model: options.embedderModel } : {}
+	};
+	if (options.secretsActive !== void 0) checks.secrets = {
+		status: "ok",
+		activeStore: options.secretsActive
+	};
+	if (options.encryptionEnabled !== void 0) {
+		const peerDepInstalled = options.cipherPeerInstalled ?? true;
+		checks.encryption = {
+			status: options.encryptionEnabled && peerDepInstalled === false ? "fail" : "ok",
+			enabled: options.encryptionEnabled,
+			peerDepInstalled
+		};
+	}
+	if (options.consolidator !== void 0) try {
+		const status$1 = await options.consolidator.status();
+		const overall = status$1.dlqSize > 0 ? "warn" : "ok";
+		checks.consolidator = {
+			status: status$1.paused ? "warn" : overall,
+			tier: status$1.tier,
+			running: status$1.running,
+			paused: status$1.paused,
+			queueDepth: status$1.queueDepth,
+			dlqSize: status$1.dlqSize,
+			budgetRemaining: {
+				tokens: status$1.budget.tokensRemaining,
+				costUsd: status$1.budget.costRemaining
+			}
+		};
+	} catch (err) {
+		checks.consolidator = {
+			status: "fail",
+			tier: "unknown",
+			running: false,
+			paused: false,
+			queueDepth: 0,
+			dlqSize: 0,
+			budgetRemaining: {
+				tokens: 0,
+				costUsd: 0
+			},
+			message: err instanceof Error ? err.message : String(err)
+		};
+	}
+	if (options.triggers !== void 0) try {
+		const status$1 = await options.triggers.status();
+		checks.triggers = {
+			status: "ok",
+			running: status$1.running,
+			active: status$1.active,
+			disabled: status$1.disabled,
+			deferred: status$1.deferred,
+			...status$1.lastFireAt !== void 0 ? { lastFireAt: status$1.lastFireAt } : {}
+		};
+	} catch (err) {
+		checks.triggers = {
+			status: "fail",
+			running: false,
+			active: 0,
+			disabled: 0,
+			deferred: 0,
+			message: err instanceof Error ? err.message : String(err)
+		};
+	}
+	if (options.replayBuffer !== void 0) {
+		const probe = options.replayBuffer;
+		checks.replayBuffer = {
+			status: "ok",
+			eventsBuffered: probe.eventsBuffered,
+			...probe.subscribers !== void 0 ? { subscribers: probe.subscribers } : {},
+			...probe.subscriptions !== void 0 ? { subscriptions: probe.subscriptions } : {}
+		};
+	}
+	const status = rollup(checks);
+	return Object.freeze({
+		status,
+		checks: Object.freeze(checks)
+	});
+}
+/**
+* Promote the worst per-check status to the rollup label.
+*
+* @stable
+*/
+function rollup(checks) {
+	let worst = "ok";
+	for (const value of Object.values(checks)) {
+		if (value === void 0) continue;
+		if (value.status === "fail") return "failing";
+		if (value.status === "warn") worst = "degraded";
+	}
+	return worst;
+}
+function readWalSizeSafely(store) {
+	try {
+		return readWalSize(store.connection);
+	} catch {
+		return 0;
+	}
+}
+
+//#endregion
+export { collectHealth, rollup };
+//# sourceMappingURL=checks.js.map

package/dist/health/checks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checks.js","names":["checks: {\n    -readonly [K in keyof HealthChecks]?: HealthChecks[K];\n  }","status","overall: HealthStatus","worst: HealthRollup"],"sources":["../../src/health/checks.ts"],"sourcesContent":["/**\n * Per-subsystem health checks aggregated by `/v1/health`. Every check\n * resolves to `'ok' | 'warn' | 'fail'`; the aggregator promotes the\n * worst status to the top-level rollup.\n *\n * The serialized shape is **flat**: each check carries its detail\n * fields directly on the same object as the `status` discriminator\n * — no nested `detail` wrapper — matching the documented response\n * contract exactly.\n *\n * @packageDocumentation\n */\n\nimport type { GraphorinSqliteStore } from '@graphorin/store-sqlite';\nimport { readWalSize } from '@graphorin/store-sqlite';\nimport type { ConsolidatorDaemon } from '../consolidator/daemon.js';\nimport type { TriggersDaemon } from '../triggers/daemon.js';\n\n/** @stable */\nexport interface ReplayBufferProbe {\n  /** Total events buffered across all subjects. Aggregated by the caller. */\n  readonly eventsBuffered: number;\n  readonly subscribers?: number;\n  readonly subscriptions?: number;\n}\n\n/** @stable */\nexport type HealthStatus = 'ok' | 'warn' | 'fail';\n\n/** @stable */\nexport type HealthRollup = 'ok' | 'degraded' | 'failing';\n\n/**\n * Common discriminator carried on every per-subsystem check entry.\n * Concrete shapes extend this with subsystem-specific fields per the\n * documented contract.\n *\n * @stable\n */\nexport interface BaseHealthCheck {\n  readonly status: HealthStatus;\n  readonly message?: string;\n}\n\n/** @stable */\nexport interface StorageCheck extends BaseHealthCheck {\n  readonly walSizeBytes: number;\n  readonly warnThresholdBytes: number;\n  readonly lastCheckpointAt?: string;\n}\n\n/** @stable */\nexport interface EmbedderCheck extends BaseHealthCheck {\n  readonly modelLoaded: boolean;\n  readonly model?: string;\n}\n\n/** @stable */\nexport interface SecretsCheck extends BaseHealthCheck {\n  readonly activeStore: string;\n}\n\n/** @stable */\nexport interface EncryptionCheck extends BaseHealthCheck {\n  readonly enabled: boolean;\n  readonly peerDepInstalled: boolean;\n}\n\n/** @stable */\nexport interface ConsolidatorCheck extends BaseHealthCheck {\n  readonly tier: string;\n  readonly running: boolean;\n  readonly paused: boolean;\n  readonly queueDepth: number;\n  readonly dlqSize: number;\n  readonly budgetRemaining: {\n    readonly tokens: number;\n    readonly costUsd: number;\n  };\n}\n\n/** @stable */\nexport interface TriggersCheck extends BaseHealthCheck {\n  readonly running: boolean;\n  readonly active: number;\n  readonly disabled: number;\n  readonly deferred: number;\n  readonly lastFireAt?: string;\n}\n\n/** @stable */\nexport interface ReplayBufferCheck extends BaseHealthCheck {\n  readonly eventsBuffered: number;\n  readonly subscribers?: number;\n  readonly subscriptions?: number;\n}\n\n/** @stable */\nexport type HealthCheck =\n  | StorageCheck\n  | EmbedderCheck\n  | SecretsCheck\n  | EncryptionCheck\n  | ConsolidatorCheck\n  | TriggersCheck\n  | ReplayBufferCheck;\n\n/** @stable */\nexport interface HealthChecks {\n  readonly storage?: StorageCheck;\n  readonly embedder?: EmbedderCheck;\n  readonly secrets?: SecretsCheck;\n  readonly encryption?: EncryptionCheck;\n  readonly consolidator?: ConsolidatorCheck;\n  readonly triggers?: TriggersCheck;\n  readonly replayBuffer?: ReplayBufferCheck;\n}\n\n/** @stable */\nexport interface HealthSummary {\n  readonly status: HealthRollup;\n  readonly checks: HealthChecks;\n}\n\n/** @stable */\nexport interface HealthCheckOptions {\n  readonly store?: GraphorinSqliteStore;\n  readonly triggers?: TriggersDaemon;\n  readonly consolidator?: ConsolidatorDaemon;\n  readonly replayBuffer?: ReplayBufferProbe;\n  readonly secretsActive?: string;\n  readonly encryptionEnabled?: boolean;\n  readonly cipherPeerInstalled?: boolean;\n  readonly embedderModel?: string;\n  readonly embedderLoaded?: boolean;\n  /** Highest acceptable WAL size in bytes before warning. Default 50 MB. */\n  readonly walWarnThresholdBytes?: number;\n}\n\nconst DEFAULT_WAL_WARN_THRESHOLD_BYTES = 50 * 1024 * 1024;\n\n/**\n * Build the aggregate health summary from runtime probes.\n *\n * @stable\n */\nexport async function collectHealth(options: HealthCheckOptions): Promise<HealthSummary> {\n  const checks: {\n    -readonly [K in keyof HealthChecks]?: HealthChecks[K];\n  } = {};\n\n  if (options.store !== undefined) {\n    const walSize = readWalSizeSafely(options.store);\n    const threshold = options.walWarnThresholdBytes ?? DEFAULT_WAL_WARN_THRESHOLD_BYTES;\n    const status: HealthStatus = walSize > threshold ? 'warn' : 'ok';\n    checks.storage = {\n      status,\n      walSizeBytes: walSize,\n      warnThresholdBytes: threshold,\n    };\n  }\n\n  if (options.embedderLoaded !== undefined) {\n    checks.embedder = {\n      status: options.embedderLoaded ? 'ok' : 'warn',\n      modelLoaded: options.embedderLoaded,\n      ...(options.embedderModel !== undefined ? { model: options.embedderModel } : {}),\n    };\n  }\n\n  if (options.secretsActive !== undefined) {\n    checks.secrets = {\n      status: 'ok',\n      activeStore: options.secretsActive,\n    };\n  }\n\n  if (options.encryptionEnabled !== undefined) {\n    // IP-1: a server that is serving this health endpoint with\n    // encryption enabled has already opened the store WITH its key at\n    // boot (createServer threads the resolved passphrase into\n    // createSqliteStore and fails fast otherwise) — that successful\n    // keyed open is the factual basis of this check. 'fail' is\n    // reserved for an explicit negative cipher-peer probe; the old\n    // default blamed a missing peer dep on every encrypted boot.\n    const peerDepInstalled = options.cipherPeerInstalled ?? true;\n    checks.encryption = {\n      status: options.encryptionEnabled && peerDepInstalled === false ? 'fail' : 'ok',\n      enabled: options.encryptionEnabled,\n      peerDepInstalled,\n    };\n  }\n\n  if (options.consolidator !== undefined) {\n    try {\n      const status = await options.consolidator.status();\n      const overall: HealthStatus = status.dlqSize > 0 ? 'warn' : 'ok';\n      checks.consolidator = {\n        status: status.paused ? 'warn' : overall,\n        tier: status.tier,\n        running: status.running,\n        paused: status.paused,\n        queueDepth: status.queueDepth,\n        dlqSize: status.dlqSize,\n        budgetRemaining: {\n          tokens: status.budget.tokensRemaining,\n          costUsd: status.budget.costRemaining,\n        },\n      };\n    } catch (err) {\n      checks.consolidator = {\n        status: 'fail',\n        tier: 'unknown',\n        running: false,\n        paused: false,\n        queueDepth: 0,\n        dlqSize: 0,\n        budgetRemaining: { tokens: 0, costUsd: 0 },\n        message: err instanceof Error ? err.message : String(err),\n      };\n    }\n  }\n\n  if (options.triggers !== undefined) {\n    try {\n      const status = await options.triggers.status();\n      checks.triggers = {\n        status: 'ok',\n        running: status.running,\n        active: status.active,\n        disabled: status.disabled,\n        deferred: status.deferred,\n        ...(status.lastFireAt !== undefined ? { lastFireAt: status.lastFireAt } : {}),\n      };\n    } catch (err) {\n      checks.triggers = {\n        status: 'fail',\n        running: false,\n        active: 0,\n        disabled: 0,\n        deferred: 0,\n        message: err instanceof Error ? err.message : String(err),\n      };\n    }\n  }\n\n  if (options.replayBuffer !== undefined) {\n    const probe = options.replayBuffer;\n    checks.replayBuffer = {\n      status: 'ok',\n      eventsBuffered: probe.eventsBuffered,\n      ...(probe.subscribers !== undefined ? { subscribers: probe.subscribers } : {}),\n      ...(probe.subscriptions !== undefined ? { subscriptions: probe.subscriptions } : {}),\n    };\n  }\n\n  const status = rollup(checks);\n  return Object.freeze({ status, checks: Object.freeze(checks) as HealthChecks });\n}\n\n/**\n * Promote the worst per-check status to the rollup label.\n *\n * @stable\n */\nexport function rollup(checks: HealthChecks): HealthRollup {\n  let worst: HealthRollup = 'ok';\n  for (const value of Object.values(checks)) {\n    if (value === undefined) continue;\n    if (value.status === 'fail') return 'failing';\n    if (value.status === 'warn') worst = 'degraded';\n  }\n  return worst;\n}\n\nfunction readWalSizeSafely(store: GraphorinSqliteStore): number {\n  try {\n    return readWalSize(store.connection);\n  } catch {\n    return 0;\n  }\n}\n"],"mappings":";;;AA2IA,MAAM,mCAAmC,KAAK,OAAO;;;;;;AAOrD,eAAsB,cAAc,SAAqD;CACvF,MAAMA,SAEF,EAAE;AAEN,KAAI,QAAQ,UAAU,QAAW;EAC/B,MAAM,UAAU,kBAAkB,QAAQ,MAAM;EAChD,MAAM,YAAY,QAAQ,yBAAyB;AAEnD,SAAO,UAAU;GACf,QAF2B,UAAU,YAAY,SAAS;GAG1D,cAAc;GACd,oBAAoB;GACrB;;AAGH,KAAI,QAAQ,mBAAmB,OAC7B,QAAO,WAAW;EAChB,QAAQ,QAAQ,iBAAiB,OAAO;EACxC,aAAa,QAAQ;EACrB,GAAI,QAAQ,kBAAkB,SAAY,EAAE,OAAO,QAAQ,eAAe,GAAG,EAAE;EAChF;AAGH,KAAI,QAAQ,kBAAkB,OAC5B,QAAO,UAAU;EACf,QAAQ;EACR,aAAa,QAAQ;EACtB;AAGH,KAAI,QAAQ,sBAAsB,QAAW;EAQ3C,MAAM,mBAAmB,QAAQ,uBAAuB;AACxD,SAAO,aAAa;GAClB,QAAQ,QAAQ,qBAAqB,qBAAqB,QAAQ,SAAS;GAC3E,SAAS,QAAQ;GACjB;GACD;;AAGH,KAAI,QAAQ,iBAAiB,OAC3B,KAAI;EACF,MAAMC,WAAS,MAAM,QAAQ,aAAa,QAAQ;EAClD,MAAMC,UAAwBD,SAAO,UAAU,IAAI,SAAS;AAC5D,SAAO,eAAe;GACpB,QAAQA,SAAO,SAAS,SAAS;GACjC,MAAMA,SAAO;GACb,SAASA,SAAO;GAChB,QAAQA,SAAO;GACf,YAAYA,SAAO;GACnB,SAASA,SAAO;GAChB,iBAAiB;IACf,QAAQA,SAAO,OAAO;IACtB,SAASA,SAAO,OAAO;IACxB;GACF;UACM,KAAK;AACZ,SAAO,eAAe;GACpB,QAAQ;GACR,MAAM;GACN,SAAS;GACT,QAAQ;GACR,YAAY;GACZ,SAAS;GACT,iBAAiB;IAAE,QAAQ;IAAG,SAAS;IAAG;GAC1C,SAAS,eAAe,QAAQ,IAAI,UAAU,OAAO,IAAI;GAC1D;;AAIL,KAAI,QAAQ,aAAa,OACvB,KAAI;EACF,MAAMA,WAAS,MAAM,QAAQ,SAAS,QAAQ;AAC9C,SAAO,WAAW;GAChB,QAAQ;GACR,SAASA,SAAO;GAChB,QAAQA,SAAO;GACf,UAAUA,SAAO;GACjB,UAAUA,SAAO;GACjB,GAAIA,SAAO,eAAe,SAAY,EAAE,YAAYA,SAAO,YAAY,GAAG,EAAE;GAC7E;UACM,KAAK;AACZ,SAAO,WAAW;GAChB,QAAQ;GACR,SAAS;GACT,QAAQ;GACR,UAAU;GACV,UAAU;GACV,SAAS,eAAe,QAAQ,IAAI,UAAU,OAAO,IAAI;GAC1D;;AAIL,KAAI,QAAQ,iBAAiB,QAAW;EACtC,MAAM,QAAQ,QAAQ;AACtB,SAAO,eAAe;GACpB,QAAQ;GACR,gBAAgB,MAAM;GACtB,GAAI,MAAM,gBAAgB,SAAY,EAAE,aAAa,MAAM,aAAa,GAAG,EAAE;GAC7E,GAAI,MAAM,kBAAkB,SAAY,EAAE,eAAe,MAAM,eAAe,GAAG,EAAE;GACpF;;CAGH,MAAM,SAAS,OAAO,OAAO;AAC7B,QAAO,OAAO,OAAO;EAAE;EAAQ,QAAQ,OAAO,OAAO,OAAO;EAAkB,CAAC;;;;;;;AAQjF,SAAgB,OAAO,QAAoC;CACzD,IAAIE,QAAsB;AAC1B,MAAK,MAAM,SAAS,OAAO,OAAO,OAAO,EAAE;AACzC,MAAI,UAAU,OAAW;AACzB,MAAI,MAAM,WAAW,OAAQ,QAAO;AACpC,MAAI,MAAM,WAAW,OAAQ,SAAQ;;AAEvC,QAAO;;AAGT,SAAS,kBAAkB,OAAqC;AAC9D,KAAI;AACF,SAAO,YAAY,MAAM,WAAW;SAC9B;AACN,SAAO"}

package/dist/health/index.d.ts

@@ -0,0 +1,3 @@
+import { BaseHealthCheck, ConsolidatorCheck, EmbedderCheck, EncryptionCheck, HealthCheck, HealthCheckOptions, HealthChecks, HealthRollup, HealthStatus, HealthSummary, ReplayBufferCheck, ReplayBufferProbe, SecretsCheck, StorageCheck, TriggersCheck, collectHealth, rollup } from "./checks.js";
+import { HealthRouteOptions, MetricsRoutesOptions, createExtendedHealthRoutes, createMetricsRoutes, createSecretsHealthRoutes } from "./routes.js";
+export { type BaseHealthCheck, type ConsolidatorCheck, type EmbedderCheck, type EncryptionCheck, type HealthCheck, type HealthCheckOptions, type HealthChecks, type HealthRollup, type HealthRouteOptions, type HealthStatus, type HealthSummary, type MetricsRoutesOptions, type ReplayBufferCheck, type ReplayBufferProbe, type SecretsCheck, type StorageCheck, type TriggersCheck, collectHealth, createExtendedHealthRoutes, createMetricsRoutes, createSecretsHealthRoutes, rollup };

package/dist/health/index.js

@@ -0,0 +1,4 @@
+import { collectHealth, rollup } from "./checks.js";
+import { createExtendedHealthRoutes, createMetricsRoutes, createSecretsHealthRoutes } from "./routes.js";
+
+export { collectHealth, createExtendedHealthRoutes, createMetricsRoutes, createSecretsHealthRoutes, rollup };

package/dist/health/routes.d.ts

@@ -0,0 +1,66 @@
+import { HealthCheckOptions } from "./checks.js";
+import { ServerVariables } from "../internal/context.js";
+import { MetricRegistry } from "../metrics/registry.js";
+import { Hono } from "hono";
+
+//#region src/health/routes.d.ts
+
+/**
+ * @stable
+ */
+interface HealthRouteOptions {
+  readonly version: string;
+  readonly startedAt: number;
+  readonly now?: () => number;
+  readonly probes: () => HealthCheckOptions | Promise<HealthCheckOptions>;
+}
+/**
+ * Public health route (anonymous; mounted before auth middleware).
+ * Returns the rollup + per-check breakdown; HTTP 200 even when the
+ * rollup is `'degraded'` so liveness probes do not flap on minor
+ * degradations. Only `'failing'` short-circuits with 503.
+ *
+ * @stable
+ */
+declare function createExtendedHealthRoutes(options: HealthRouteOptions): Hono<{
+  Variables: ServerVariables;
+}>;
+/**
+ * Authed health route. Mounted at `${base}/health/secrets` AFTER the
+ * auth middleware so the scope check has a verified token to inspect.
+ * Returns the active secrets store + fallback chain + downgrade
+ * reason per the secrets capability matrix.
+ *
+ * @stable
+ */
+declare function createSecretsHealthRoutes(): Hono<{
+  Variables: ServerVariables;
+}>;
+/**
+ * @stable
+ */
+interface MetricsRoutesOptions {
+  readonly registry: MetricRegistry;
+  readonly requireAuth?: boolean;
+  /**
+   * Optional refresh callback invoked before every scrape. Use it to
+   * sample live signals (WAL size, in-flight runs, daemon status,
+   * replay buffer occupancy) into the registry so the scraped output
+   * reflects the moment of the request.
+   *
+   * Refresh failures are swallowed — a broken probe never blocks a
+   * Prometheus scrape — and surfaced through the optional `onError`
+   * sink.
+   */
+  readonly refresh?: () => void | Promise<void>;
+  readonly onError?: (err: unknown) => void;
+}
+/**
+ * @stable
+ */
+declare function createMetricsRoutes(options: MetricsRoutesOptions): Hono<{
+  Variables: ServerVariables;
+}>;
+//#endregion
+export { HealthRouteOptions, MetricsRoutesOptions, createExtendedHealthRoutes, createMetricsRoutes, createSecretsHealthRoutes };
+//# sourceMappingURL=routes.d.ts.map

package/dist/health/routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.d.ts","names":[],"sources":["../../src/health/routes.ts"],"sourcesContent":[],"mappings":";;;;;;;AA+GA;AAoBA;;AAEqB,UA3GJ,kBAAA,CA2GI;EAAlB,SAAA,OAAA,EAAA,MAAA;EAAI,SAAA,SAAA,EAAA,MAAA;;yBAvGkB,qBAAqB,QAAQ;;;;;;;;;;iBAWtC,0BAAA,UACL,qBACR;aAAkB;;;;;;;;;;iBA8BL,yBAAA,CAAA,GAA6B;aAAkB;;;;;UAsC9C,oBAAA;qBACI;;;;;;;;;;;;kCAYa;;;;;;iBAOlB,mBAAA,UACL,uBACR;aAAkB"}

package/dist/health/routes.js

@@ -0,0 +1,96 @@
+import { collectHealth } from "./checks.js";
+import { createScopeMiddleware } from "../middleware/scope.js";
+import { Hono } from "hono";
+import { getSecretsStoreStatus } from "@graphorin/security/secrets";
+
+//#region src/health/routes.ts
+/**
+* Health-family REST routes.
+*
+*   GET    /health                       (unauthenticated; liveness)
+*   GET    /health/secrets               (admin scope)
+*   GET    /metrics                      (Prometheus exposition)
+*
+* `/health` returns 200 even when the rollup is `'degraded'`; only
+* `'failing'` short-circuits with 503 so liveness probes do not flap
+* on minor degradations (e.g. WAL above the warn threshold).
+*
+* @packageDocumentation
+*/
+/**
+* Public health route (anonymous; mounted before auth middleware).
+* Returns the rollup + per-check breakdown; HTTP 200 even when the
+* rollup is `'degraded'` so liveness probes do not flap on minor
+* degradations. Only `'failing'` short-circuits with 503.
+*
+* @stable
+*/
+function createExtendedHealthRoutes(options) {
+	const app = new Hono();
+	const now = options.now ?? Date.now;
+	app.get("/", async (c) => {
+		const summary = await collectHealth(await options.probes());
+		const body = {
+			status: summary.status,
+			version: options.version,
+			uptimeSeconds: Math.max(0, Math.floor((now() - options.startedAt) / 1e3)),
+			checks: summary.checks
+		};
+		if (summary.status === "failing") return c.json(body, 503);
+		return c.json(body, 200);
+	});
+	return app;
+}
+/**
+* Authed health route. Mounted at `${base}/health/secrets` AFTER the
+* auth middleware so the scope check has a verified token to inspect.
+* Returns the active secrets store + fallback chain + downgrade
+* reason per the secrets capability matrix.
+*
+* @stable
+*/
+function createSecretsHealthRoutes() {
+	const app = new Hono();
+	app.get("/", createScopeMiddleware("secrets:read"), (c) => {
+		const status = getSecretsStoreStatus();
+		if (status === void 0) return c.json({
+			active: "unknown",
+			fallbackChain: [],
+			strictMode: false,
+			headlessReasons: [],
+			message: "Secrets store has not been activated yet."
+		}, 200);
+		return c.json({
+			active: status.active,
+			fallbackChain: [...status.fallbackChain],
+			...status.downgradedFrom !== void 0 ? { downgradedFrom: status.downgradedFrom } : {},
+			...status.downgradeReason !== void 0 ? { downgradeReason: status.downgradeReason } : {},
+			strictMode: status.strictMode,
+			headlessReasons: [...status.headlessReasons]
+		}, 200);
+	});
+	return app;
+}
+/**
+* @stable
+*/
+function createMetricsRoutes(options) {
+	const app = new Hono();
+	const handler = async (c) => {
+		if (options.refresh !== void 0) try {
+			await options.refresh();
+		} catch (err) {
+			options.onError?.(err);
+		}
+		const body = options.registry.render();
+		c.header("Content-Type", options.registry.contentType());
+		return c.body(body, 200);
+	};
+	if (options.requireAuth === true) app.get("/", createScopeMiddleware("admin:metrics:read"), handler);
+	else app.get("/", handler);
+	return app;
+}
+
+//#endregion
+export { createExtendedHealthRoutes, createMetricsRoutes, createSecretsHealthRoutes };
+//# sourceMappingURL=routes.js.map

package/dist/health/routes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.js","names":[],"sources":["../../src/health/routes.ts"],"sourcesContent":["/**\n * Health-family REST routes.\n *\n *   GET    /health                       (unauthenticated; liveness)\n *   GET    /health/secrets               (admin scope)\n *   GET    /metrics                      (Prometheus exposition)\n *\n * `/health` returns 200 even when the rollup is `'degraded'`; only\n * `'failing'` short-circuits with 503 so liveness probes do not flap\n * on minor degradations (e.g. WAL above the warn threshold).\n *\n * @packageDocumentation\n */\n\nimport { getSecretsStoreStatus } from '@graphorin/security/secrets';\nimport type { Context } from 'hono';\nimport { Hono } from 'hono';\n\nimport type { ServerVariables } from '../internal/context.js';\nimport type { MetricRegistry } from '../metrics/registry.js';\nimport { createScopeMiddleware } from '../middleware/scope.js';\nimport { collectHealth, type HealthCheckOptions } from './checks.js';\n\n/**\n * @stable\n */\nexport interface HealthRouteOptions {\n  readonly version: string;\n  readonly startedAt: number;\n  readonly now?: () => number;\n  readonly probes: () => HealthCheckOptions | Promise<HealthCheckOptions>;\n}\n\n/**\n * Public health route (anonymous; mounted before auth middleware).\n * Returns the rollup + per-check breakdown; HTTP 200 even when the\n * rollup is `'degraded'` so liveness probes do not flap on minor\n * degradations. Only `'failing'` short-circuits with 503.\n *\n * @stable\n */\nexport function createExtendedHealthRoutes(\n  options: HealthRouteOptions,\n): Hono<{ Variables: ServerVariables }> {\n  const app = new Hono<{ Variables: ServerVariables }>();\n  const now = options.now ?? Date.now;\n\n  app.get('/', async (c) => {\n    const probes = await options.probes();\n    const summary = await collectHealth(probes);\n    const body = {\n      status: summary.status,\n      version: options.version,\n      uptimeSeconds: Math.max(0, Math.floor((now() - options.startedAt) / 1000)),\n      checks: summary.checks,\n    };\n    if (summary.status === 'failing') {\n      return c.json(body, 503);\n    }\n    return c.json(body, 200);\n  });\n\n  return app;\n}\n\n/**\n * Authed health route. Mounted at `${base}/health/secrets` AFTER the\n * auth middleware so the scope check has a verified token to inspect.\n * Returns the active secrets store + fallback chain + downgrade\n * reason per the secrets capability matrix.\n *\n * @stable\n */\nexport function createSecretsHealthRoutes(): Hono<{ Variables: ServerVariables }> {\n  const app = new Hono<{ Variables: ServerVariables }>();\n\n  app.get('/', createScopeMiddleware('secrets:read'), (c) => {\n    const status = getSecretsStoreStatus();\n    if (status === undefined) {\n      return c.json(\n        {\n          active: 'unknown',\n          fallbackChain: [] as ReadonlyArray<string>,\n          strictMode: false,\n          headlessReasons: [] as ReadonlyArray<string>,\n          message: 'Secrets store has not been activated yet.',\n        },\n        200,\n      );\n    }\n    return c.json(\n      {\n        active: status.active,\n        fallbackChain: [...status.fallbackChain],\n        ...(status.downgradedFrom !== undefined ? { downgradedFrom: status.downgradedFrom } : {}),\n        ...(status.downgradeReason !== undefined\n          ? { downgradeReason: status.downgradeReason }\n          : {}),\n        strictMode: status.strictMode,\n        headlessReasons: [...status.headlessReasons],\n      },\n      200,\n    );\n  });\n\n  return app;\n}\n\n/**\n * @stable\n */\nexport interface MetricsRoutesOptions {\n  readonly registry: MetricRegistry;\n  readonly requireAuth?: boolean;\n  /**\n   * Optional refresh callback invoked before every scrape. Use it to\n   * sample live signals (WAL size, in-flight runs, daemon status,\n   * replay buffer occupancy) into the registry so the scraped output\n   * reflects the moment of the request.\n   *\n   * Refresh failures are swallowed — a broken probe never blocks a\n   * Prometheus scrape — and surfaced through the optional `onError`\n   * sink.\n   */\n  readonly refresh?: () => void | Promise<void>;\n  readonly onError?: (err: unknown) => void;\n}\n\n/**\n * @stable\n */\nexport function createMetricsRoutes(\n  options: MetricsRoutesOptions,\n): Hono<{ Variables: ServerVariables }> {\n  const app = new Hono<{ Variables: ServerVariables }>();\n  const handler = async (c: Context<{ Variables: ServerVariables }>) => {\n    if (options.refresh !== undefined) {\n      try {\n        await options.refresh();\n      } catch (err) {\n        options.onError?.(err);\n      }\n    }\n    const body = options.registry.render();\n    c.header('Content-Type', options.registry.contentType());\n    return c.body(body, 200);\n  };\n  if (options.requireAuth === true) {\n    app.get('/', createScopeMiddleware('admin:metrics:read'), handler);\n  } else {\n    app.get('/', handler);\n  }\n  return app;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AAyCA,SAAgB,2BACd,SACsC;CACtC,MAAM,MAAM,IAAI,MAAsC;CACtD,MAAM,MAAM,QAAQ,OAAO,KAAK;AAEhC,KAAI,IAAI,KAAK,OAAO,MAAM;EAExB,MAAM,UAAU,MAAM,cADP,MAAM,QAAQ,QAAQ,CACM;EAC3C,MAAM,OAAO;GACX,QAAQ,QAAQ;GAChB,SAAS,QAAQ;GACjB,eAAe,KAAK,IAAI,GAAG,KAAK,OAAO,KAAK,GAAG,QAAQ,aAAa,IAAK,CAAC;GAC1E,QAAQ,QAAQ;GACjB;AACD,MAAI,QAAQ,WAAW,UACrB,QAAO,EAAE,KAAK,MAAM,IAAI;AAE1B,SAAO,EAAE,KAAK,MAAM,IAAI;GACxB;AAEF,QAAO;;;;;;;;;;AAWT,SAAgB,4BAAkE;CAChF,MAAM,MAAM,IAAI,MAAsC;AAEtD,KAAI,IAAI,KAAK,sBAAsB,eAAe,GAAG,MAAM;EACzD,MAAM,SAAS,uBAAuB;AACtC,MAAI,WAAW,OACb,QAAO,EAAE,KACP;GACE,QAAQ;GACR,eAAe,EAAE;GACjB,YAAY;GACZ,iBAAiB,EAAE;GACnB,SAAS;GACV,EACD,IACD;AAEH,SAAO,EAAE,KACP;GACE,QAAQ,OAAO;GACf,eAAe,CAAC,GAAG,OAAO,cAAc;GACxC,GAAI,OAAO,mBAAmB,SAAY,EAAE,gBAAgB,OAAO,gBAAgB,GAAG,EAAE;GACxF,GAAI,OAAO,oBAAoB,SAC3B,EAAE,iBAAiB,OAAO,iBAAiB,GAC3C,EAAE;GACN,YAAY,OAAO;GACnB,iBAAiB,CAAC,GAAG,OAAO,gBAAgB;GAC7C,EACD,IACD;GACD;AAEF,QAAO;;;;;AA0BT,SAAgB,oBACd,SACsC;CACtC,MAAM,MAAM,IAAI,MAAsC;CACtD,MAAM,UAAU,OAAO,MAA+C;AACpE,MAAI,QAAQ,YAAY,OACtB,KAAI;AACF,SAAM,QAAQ,SAAS;WAChB,KAAK;AACZ,WAAQ,UAAU,IAAI;;EAG1B,MAAM,OAAO,QAAQ,SAAS,QAAQ;AACtC,IAAE,OAAO,gBAAgB,QAAQ,SAAS,aAAa,CAAC;AACxD,SAAO,EAAE,KAAK,MAAM,IAAI;;AAE1B,KAAI,QAAQ,gBAAgB,KAC1B,KAAI,IAAI,KAAK,sBAAsB,qBAAqB,EAAE,QAAQ;KAElE,KAAI,IAAI,KAAK,QAAQ;AAEvB,QAAO"}

package/dist/index.d.ts

@@ -0,0 +1,88 @@
+import { DeliveryCommentaryConfig, DeliveryCommentaryDecision, DeliveryCommentaryPattern, DeliveryCommentaryPolicy, DeliveryCommentaryReason, DeliveryCommentarySink, DeliveryCommentaryTransport } from "./commentary/types.js";
+import { DEFAULT_APPLY_TO_EVENTS, DEFAULT_DELIVERY_COMMENTARY_PATTERNS } from "./commentary/built-in-patterns.js";
+import { DeliveryCommentarySanitizer, createDeliveryCommentarySanitizer } from "./commentary/sanitizer.js";
+import "./commentary/index.js";
+import { DeliveryCommentaryPolicyConfig, IdempotencyRequireKeyMode, SecretRefString, SecretsSource, ServerConfigInput, ServerConfigSchema, ServerConfigSpec, defineConfig, parseServerConfig } from "./config.js";
+import { ConsolidatorDaemon, ConsolidatorLike, ConsolidatorStatusLike, CreateConsolidatorDaemonOptions, createConsolidatorDaemon } from "./consolidator/daemon.js";
+import "./consolidator/index.js";
+import { AgentNotFoundError, ConfigInvalidError, GraphorinServerError, GraphorinServerErrorCode, IdempotencyConflictError, IdempotencyKeyRequiredError, LifecycleDoubleStartError, LifecycleNotStartedError, MigrationFailedError, PrebindEncryptionPeerMissingError, PrebindEncryptionRequiredError, PrebindPepperMissingError, PrebindSecretUnresolvableError, RouteHandlerMissingError, ShutdownTimeoutError, WorkflowNotFoundError } from "./errors/index.js";
+import { CreateTriggersDaemonOptions, TriggersDaemon, TriggersDaemonMetrics, TriggersDaemonStatus, createTriggersDaemon, defaultCatchupPolicy } from "./triggers/daemon.js";
+import { BaseHealthCheck, ConsolidatorCheck, EmbedderCheck, EncryptionCheck, HealthCheck, HealthCheckOptions, HealthChecks, HealthRollup, HealthStatus, HealthSummary, ReplayBufferCheck, ReplayBufferProbe, SecretsCheck, StorageCheck, TriggersCheck, collectHealth, rollup } from "./health/checks.js";
+import { RequestToken, ServerRequestState, ServerVariables } from "./internal/context.js";
+import { LabelSet, MetricKind, MetricRegistry } from "./metrics/registry.js";
+import { HealthRouteOptions, MetricsRoutesOptions, createExtendedHealthRoutes, createMetricsRoutes, createSecretsHealthRoutes } from "./health/routes.js";
+import "./health/index.js";
+import { BeforeShutdownContext, BeforeStartContext, LifecycleHooks, OnErrorContext, OnReadyContext } from "./lifecycle/hooks.js";
+import { PreBindResult, RunPreBindOptions, runPreBind } from "./lifecycle/pre-bind.js";
+import "./lifecycle/index.js";
+import { AgentRegistration, AgentRegistry, AgentSummary, ServerAgentLike, ServerWorkflowLike, WorkflowRegistration, WorkflowRegistry, WorkflowSummary } from "./registry/index.js";
+import { ReplayApi, ReplayMode, ReplayResponse, ReplayRoutesDeps, createReplayRoutes } from "./replay/routes.js";
+import "./replay/index.js";
+import { ReplayBuffer, ReplayBufferOptions, ReplayBufferSlice, createReplayBuffer } from "./ws/replay-buffer.js";
+import { ParsedSubject, requiredScopeFor, tryParseSubject } from "./ws/subjects.js";
+import { BareEventFrame, SubscribeResult, WsDispatcher, WsDispatcherOptions, WsDispatcherWarning, WsSubscriberHandle, WsSubscriptionSnapshot, createWsDispatcher } from "./ws/dispatcher.js";
+import { RunDescriptor, RunHandle, RunStateSnapshot, RunStateTracker, RunStatus } from "./runtime/run-state.js";
+import { AgentRoutesDeps, createAgentRoutes, createRunRoutes } from "./routes/agents.js";
+import { AuditApi, AuditRoutesDeps, createAuditRoutes } from "./routes/audit.js";
+import { WsTicket, WsTicketConsumeResult, WsTicketStore, WsTicketStoreOptions, createWsTicketStore } from "./ws/ticket.js";
+import { AuthRoutesDeps, createAuthRoutes } from "./routes/auth.js";
+import { HealthRoutesDeps, createHealthRoutes } from "./routes/health.js";
+import { McpApi, McpRoutesDeps, createMcpRoutes } from "./routes/mcp.js";
+import { MemoryApi, MemoryRoutesDeps, createMemoryRoutes } from "./routes/memory.js";
+import { SessionApi, SessionRoutesDeps, createSessionRoutes } from "./routes/sessions.js";
+import { SkillsApi, SkillsRoutesDeps, createSkillsRoutes } from "./routes/skills.js";
+import { TokensRoutesDeps, createTokensRoutes } from "./routes/tokens.js";
+import { WorkflowRoutesDeps, createWorkflowRoutes } from "./routes/workflows.js";
+import "./routes/index.js";
+import { WsUpgradeOptions, createWsUpgradeEvents } from "./ws/upgrade.js";
+import "./ws/index.js";
+import { CreateServerOptions, GraphorinServer, TriggersDaemonInput, createServer, ensureStoreAuditBinding } from "./app.js";
+import { SERVER_METRIC_NAMES, createServerMetricRegistry } from "./metrics/catalog.js";
+import { AuditErrorSink, AuditMiddlewareOptions, HTTP_REQUEST_AUDIT_ACTION, createAuditMiddleware } from "./middleware/audit.js";
+import { AuthMiddlewareOptions, createAuthMiddleware } from "./middleware/auth.js";
+import { createCorsMiddleware } from "./middleware/cors.js";
+import { createCsrfMiddleware } from "./middleware/csrf.js";
+import { IdempotencyMiddlewareOptions, createIdempotencyMiddleware } from "./middleware/idempotency.js";
+import { createRateLimitMiddleware } from "./middleware/rate-limit.js";
+import { RequestStateMiddlewareOptions, createRequestStateMiddleware } from "./middleware/request-state.js";
+import { ScopeRequirement, createScopeMiddleware } from "./middleware/scope.js";
+import "./middleware/index.js";
+import { SseRoutesDeps, createSseRoutes } from "./sse/events.js";
+import "./sse/index.js";
+import { TriggersRoutesDeps, createTriggersRoutes } from "./triggers/routes.js";
+import "./triggers/index.js";
+
+//#region src/index.d.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. */
+declare const VERSION = "0.5.0";
+//#endregion
+export { AgentNotFoundError, type AgentRegistration, AgentRegistry, type AgentRoutesDeps, type AgentSummary, type AuditApi, type AuditErrorSink, type AuditMiddlewareOptions, type AuditRoutesDeps, type AuthMiddlewareOptions, type AuthRoutesDeps, type BareEventFrame, type BaseHealthCheck, type BeforeShutdownContext, type BeforeStartContext, ConfigInvalidError, type ConsolidatorCheck, type ConsolidatorDaemon, type ConsolidatorLike, type ConsolidatorStatusLike, type CreateConsolidatorDaemonOptions, type CreateServerOptions, type CreateTriggersDaemonOptions, DEFAULT_APPLY_TO_EVENTS, DEFAULT_DELIVERY_COMMENTARY_PATTERNS, type DeliveryCommentaryConfig, type DeliveryCommentaryDecision, type DeliveryCommentaryPattern, type DeliveryCommentaryPolicy, type DeliveryCommentaryPolicyConfig, type DeliveryCommentaryReason, type DeliveryCommentarySanitizer, type DeliveryCommentarySink, type DeliveryCommentaryTransport, type EmbedderCheck, type EncryptionCheck, type GraphorinServer, GraphorinServerError, GraphorinServerErrorCode, HTTP_REQUEST_AUDIT_ACTION, type HealthCheck, type HealthCheckOptions, type HealthChecks, type HealthRollup, type HealthRouteOptions, type HealthRoutesDeps, type HealthStatus, type HealthSummary, IdempotencyConflictError, IdempotencyKeyRequiredError, type IdempotencyMiddlewareOptions, type IdempotencyRequireKeyMode, type LabelSet, LifecycleDoubleStartError, type LifecycleHooks, LifecycleNotStartedError, type McpApi, type McpRoutesDeps, type MemoryApi, type MemoryRoutesDeps, type MetricKind, MetricRegistry, type MetricsRoutesOptions, MigrationFailedError, type OnErrorContext, type OnReadyContext, type ParsedSubject, type PreBindResult, PrebindEncryptionPeerMissingError, PrebindEncryptionRequiredError, PrebindPepperMissingError, PrebindSecretUnresolvableError, type ReplayApi, type ReplayBuffer, type ReplayBufferCheck, type ReplayBufferOptions, type ReplayBufferProbe, type ReplayBufferSlice, type ReplayMode, type ReplayResponse, type ReplayRoutesDeps, type RequestStateMiddlewareOptions, type RequestToken, RouteHandlerMissingError, type RunDescriptor, type RunHandle, type RunPreBindOptions, type RunStateSnapshot, RunStateTracker, type RunStatus, SERVER_METRIC_NAMES, type ScopeRequirement, type SecretRefString, type SecretsCheck, type SecretsSource, type ServerAgentLike, type ServerConfigInput, ServerConfigSchema, type ServerConfigSpec, type ServerRequestState, type ServerVariables, type ServerWorkflowLike, type SessionApi, type SessionRoutesDeps, ShutdownTimeoutError, type SkillsApi, type SkillsRoutesDeps, type SseRoutesDeps, type StorageCheck, type SubscribeResult, type TokensRoutesDeps, type TriggersCheck, type TriggersDaemon, type TriggersDaemonInput, type TriggersDaemonMetrics, type TriggersDaemonStatus, type TriggersRoutesDeps, VERSION, WorkflowNotFoundError, type WorkflowRegistration, WorkflowRegistry, type WorkflowRoutesDeps, type WorkflowSummary, type WsDispatcher, type WsDispatcherOptions, type WsDispatcherWarning, type WsSubscriberHandle, type WsSubscriptionSnapshot, type WsTicket, type WsTicketConsumeResult, type WsTicketStore, type WsTicketStoreOptions, type WsUpgradeOptions, 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.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA8Ba,OAAA"}