@arnilo/prism-server 0.0.12 → 0.0.13

package/CHANGELOG.md

@@ -1,4 +1,17 @@
 # Changelog
+
+## [0.0.13] - 2026-07-24
+
+### Changed
+
+- Released with exact 0.0.13 graph.
+
+## [0.0.12] - 2026-07-23
+
+### Added
+
+- Optional deployment seams: `createPrismHealthHandler`, `createPrismDrainController`, host `rateLimit` adapter (+ `createMemoryRateLimiter`), ownership-scoped `createPrismEventReplay` / `createPrismReplayHandler`, and `createPrismDeploymentLease` for worker/coordinator election over existing leases. No queue adapter (deferred pending measured Postgres polling need).
+
 ## [0.0.12] - 2026-07-22
 
 ### Changed

package/README.md

@@ -26,6 +26,27 @@ const response = await handler(new Request("https://api.example.test/prism/agent
 
 Routes: direct/SSE agent run, explicitly selected durable agent status/resume through `agentRuns`, direct/SSE workflow run, durable workflow enqueue/status/cancel/resume/replay, and optional ownership-scoped schedule create/list/pause/resume/trigger/delete. `agentRuns` uses core `createAgentRunLifecycle()`; no lifecycle route exists by default. All bodies, responses, events, queues, concurrency, and timeouts are bounded.
 
-Nothing is exposed by default. Authorization is required; ownership comes only from its result. No listener, framework, auth provider, user database, credential discovery, or hidden package activation ships.
+Optional deployment helpers (compose beside the API handler — no embedded listener):
+
+```ts
+import {
+  createPrismDrainController,
+  createPrismHealthHandler,
+  createMemoryRateLimiter,
+  createPrismDeploymentLease,
+} from "@arnilo/prism-server";
+
+const drain = createPrismDrainController();
+const handler = createPrismHandler({
+  agents: { support: agent },
+  authorize,
+  drain,
+  rateLimit: createMemoryRateLimiter({ maxRequests: 60, windowMs: 60_000 }),
+});
+const health = createPrismHealthHandler({ drain, ready: () => store.ping() });
+// Workers: createWorkflowCoordinator(...). Coordinators: createPrismDeploymentLease({ key: "coordinator", ... }).
+```
+
+Nothing is exposed by default. Authorization is required; ownership comes only from its result. No listener, framework, auth provider, user database, credential discovery, queue adapter, or hidden package activation ships.
 
 Full API, route, limits, security, and deployment notes: [`docs/server.md`](../../docs/server.md).

package/dist/deployment.d.ts

@@ -0,0 +1,31 @@
+import type { LeaseRecord, LeaseStore, OwnershipScope } from "@arnilo/prism";
+/** Lease namespace for process-role election (coordinator vs worker hosts). */
+export declare const PRISM_DEPLOYMENT_LEASE_NAMESPACE = "prism.server.deployment";
+export interface PrismDeploymentLeaseOptions {
+    readonly leases: LeaseStore;
+    /** Stable process / replica id. */
+    readonly ownerId: string;
+    /**
+     * Role key within the deployment namespace.
+     * Convention: `coordinator` for schedule/admission leadership; workers omit or use host-defined keys.
+     */
+    readonly key: string;
+    readonly ownership?: OwnershipScope;
+    readonly ttlMs?: number;
+}
+export interface PrismDeploymentLease {
+    readonly namespace: typeof PRISM_DEPLOYMENT_LEASE_NAMESPACE;
+    readonly key: string;
+    readonly ownerId: string;
+    tryAcquire(signal?: AbortSignal): Promise<LeaseRecord | null>;
+    renew(token: string, signal?: AbortSignal): Promise<LeaseRecord | null>;
+    release(token: string, signal?: AbortSignal): Promise<boolean>;
+    get(signal?: AbortSignal): Promise<LeaseRecord | null>;
+}
+/**
+ * Thin LeaseStore wrapper for worker/coordinator election.
+ * Workers run `createWorkflowCoordinator` (workflows package) for queued runs;
+ * a single coordinator replica holds this lease before ticking schedules / admitting drain decisions.
+ * No embedded listener or container orchestrator.
+ */
+export declare function createPrismDeploymentLease(options: PrismDeploymentLeaseOptions): PrismDeploymentLease;

package/dist/deployment.js

@@ -0,0 +1,49 @@
+import { PrismServerError } from "./types.js";
+/** Lease namespace for process-role election (coordinator vs worker hosts). */
+export const PRISM_DEPLOYMENT_LEASE_NAMESPACE = "prism.server.deployment";
+/**
+ * Thin LeaseStore wrapper for worker/coordinator election.
+ * Workers run `createWorkflowCoordinator` (workflows package) for queued runs;
+ * a single coordinator replica holds this lease before ticking schedules / admitting drain decisions.
+ * No embedded listener or container orchestrator.
+ */
+export function createPrismDeploymentLease(options) {
+    if (!options.ownerId)
+        throw new PrismServerError("ownerId is required", 500, "ERR_PRISM_SERVER_CONFIG");
+    if (!options.key)
+        throw new PrismServerError("key is required", 500, "ERR_PRISM_SERVER_CONFIG");
+    const ttlMs = options.ttlMs ?? 30_000;
+    if (!Number.isSafeInteger(ttlMs) || ttlMs < 1) {
+        throw new PrismServerError("ttlMs must be a positive safe integer", 500, "ERR_PRISM_SERVER_CONFIG");
+    }
+    const ownership = options.ownership ?? {};
+    const base = {
+        namespace: PRISM_DEPLOYMENT_LEASE_NAMESPACE,
+        key: options.key,
+        ownerId: options.ownerId,
+        ...ownership,
+    };
+    return {
+        namespace: PRISM_DEPLOYMENT_LEASE_NAMESPACE,
+        key: options.key,
+        ownerId: options.ownerId,
+        tryAcquire(signal) {
+            return options.leases.tryAcquireLease({ ...base, ttlMs, signal });
+        },
+        renew(token, signal) {
+            return options.leases.renewLease({ ...base, token, ttlMs, signal });
+        },
+        release(token, signal) {
+            return options.leases.releaseLease({ ...base, token, signal });
+        },
+        get(signal) {
+            return options.leases.getLease({
+                namespace: PRISM_DEPLOYMENT_LEASE_NAMESPACE,
+                key: options.key,
+                signal,
+                ...ownership,
+            });
+        },
+    };
+}
+//# sourceMappingURL=deployment.js.map

package/dist/drain.d.ts

@@ -0,0 +1,23 @@
+export interface PrismDrainControllerOptions {
+    /** Admit cutoff / host exit budget after `beginDrain`. Default 30s, hard 5 min. */
+    readonly deadlineMs?: number;
+}
+export interface PrismDrainSnapshot {
+    readonly status: "serving" | "draining";
+    readonly draining: boolean;
+    readonly startedAt?: string;
+    readonly deadlineAt?: string;
+    readonly deadlineMs: number;
+}
+export interface PrismDrainController {
+    readonly isDraining: boolean;
+    beginDrain(options?: {
+        readonly deadlineMs?: number;
+    }): PrismDrainSnapshot;
+    /** Rejects new admits while draining (503). Control-plane reads may skip this. */
+    assertAdmit(): void;
+    snapshot(): PrismDrainSnapshot;
+}
+export declare function createPrismDrainController(options?: PrismDrainControllerOptions): PrismDrainController;
+/** Operations that create or continue work; blocked during drain. Status/cancel/list remain open. */
+export declare function isAdmitOperation(operation: string): boolean;

package/dist/drain.js

@@ -0,0 +1,57 @@
+import { DEFAULT_DRAIN_DEADLINE_MS, HARD_DRAIN_DEADLINE_MS, resolvePrismDeploymentLimits } from "./limits.js";
+import { PrismServerError } from "./types.js";
+export function createPrismDrainController(options = {}) {
+    const defaults = resolvePrismDeploymentLimits({ drainDeadlineMs: options.deadlineMs });
+    let draining = false;
+    let startedAt;
+    let deadlineAt;
+    let deadlineMs = defaults.drainDeadlineMs;
+    return {
+        get isDraining() {
+            return draining;
+        },
+        beginDrain(input) {
+            if (!draining) {
+                draining = true;
+                startedAt = new Date().toISOString();
+                deadlineMs = resolveDeadline(input?.deadlineMs ?? options.deadlineMs ?? DEFAULT_DRAIN_DEADLINE_MS);
+                deadlineAt = new Date(Date.now() + deadlineMs).toISOString();
+            }
+            return this.snapshot();
+        },
+        assertAdmit() {
+            if (draining) {
+                throw new PrismServerError("Server is draining", 503, "ERR_PRISM_SERVER_DRAINING");
+            }
+        },
+        snapshot() {
+            return {
+                status: draining ? "draining" : "serving",
+                draining,
+                ...(startedAt === undefined ? {} : { startedAt }),
+                ...(deadlineAt === undefined ? {} : { deadlineAt }),
+                deadlineMs,
+            };
+        },
+    };
+}
+function resolveDeadline(value) {
+    if (!Number.isSafeInteger(value) || value < 1 || value > HARD_DRAIN_DEADLINE_MS) {
+        throw new RangeError(`drainDeadlineMs must be a positive safe integer <= ${HARD_DRAIN_DEADLINE_MS}`);
+    }
+    return value;
+}
+/** Operations that create or continue work; blocked during drain. Status/cancel/list remain open. */
+export function isAdmitOperation(operation) {
+    return (operation === "agent.run" ||
+        operation === "agent.stream" ||
+        operation === "agent.resume" ||
+        operation === "workflow.run" ||
+        operation === "workflow.stream" ||
+        operation === "workflow.enqueue" ||
+        operation === "workflow.resume" ||
+        operation === "workflow.replay" ||
+        operation === "schedule.create" ||
+        operation === "schedule.trigger");
+}
+//# sourceMappingURL=drain.js.map

package/dist/handler.js

@@ -1,5 +1,6 @@
-import { AgentRunStateError } from "@arnilo/prism";
+import { AgentRunStateError, assertIdentityActive, assertIdentityMatchesOwnership } from "@arnilo/prism";
 import { cancelWorkflowRun, createWorkflowEventBus, enqueueWorkflow, getWorkflowRun, replayWorkflow, resumeWorkflow, runWorkflow, } from "@arnilo/prism-workflows";
+import { isAdmitOperation } from "./drain.js";
 import { resolvePrismServerLimits } from "./limits.js";
 import { PrismServerError } from "./types.js";
 const JSON_HEADERS = { "content-type": "application/json; charset=utf-8" };
@@ -39,6 +40,24 @@ export function createPrismHandler(options) {
             const authorization = await authorize(options, request, route.operation, route.capabilityId, limits.requestTimeoutMs);
             if (!authorization)
                 throw new PrismServerError("Forbidden", 403, "ERR_PRISM_SERVER_FORBIDDEN");
+            if (options.rateLimit) {
+                const decision = await options.rateLimit({
+                    request,
+                    operation: route.operation,
+                    capabilityId: route.capabilityId,
+                    authorization,
+                    signal: request.signal,
+                });
+                if (decision !== true) {
+                    const headers = {};
+                    if (decision.retryAfterMs !== undefined && Number.isSafeInteger(decision.retryAfterMs) && decision.retryAfterMs > 0) {
+                        headers["retry-after"] = String(Math.ceil(decision.retryAfterMs / 1000));
+                    }
+                    throw new PrismServerError(decision.message ?? "Rate limit exceeded", 429, decision.code ?? "ERR_PRISM_SERVER_RATE_LIMIT", Object.keys(headers).length ? headers : undefined);
+                }
+            }
+            if (options.drain && isAdmitOperation(route.operation))
+                options.drain.assertAdmit();
             if (route.kind.startsWith("schedule-")) {
                 const selectedSchedules = options.schedules;
                 if (!selectedSchedules)
@@ -139,6 +158,7 @@ export function createPrismHandler(options) {
                     const runConfig = {
                         ...runOptions,
                         ownership: authorization.ownership,
+                        identity: authorization.identity,
                         metadata: { ...runOptions?.metadata, ...authorization.metadata },
                         redactor: options.redactor,
                         signal: owned.signal,
@@ -418,6 +438,15 @@ async function authorize(options, request, operation, capabilityId, timeoutMs) {
     }
     if (!result || !hasOwnership(result.ownership))
         return false;
+    if (result.identity) {
+        try {
+            assertIdentityActive(result.identity);
+            assertIdentityMatchesOwnership(result.identity, result.ownership);
+        }
+        catch {
+            return false;
+        }
+    }
     return result;
 }
 function hasOwnership(value) {
@@ -693,7 +722,10 @@ function errorResponse(error, limits, options) {
     const code = mapped?.code ?? (agentState ? "ERR_PRISM_SERVER_NOT_FOUND" : known ? error.code : status === 499 ? "ERR_PRISM_SERVER_ABORTED" : "ERR_PRISM_SERVER_INTERNAL");
     const message = mapped?.message ?? (agentState ? "Not found" : known ? error.message : status === 499 ? "Request aborted" : "Internal server error");
     try {
-        return json({ error: { code, message } }, status, limits, options);
+        const response = json({ error: { code, message } }, status, limits, options);
+        if (known && error.headers)
+            return addHeaders(response, error.headers);
+        return response;
     }
     catch {
         return new Response(null, { status });

package/dist/health.d.ts

@@ -0,0 +1,20 @@
+import { type PrismDeploymentLimits } from "./limits.js";
+import type { PrismDrainController } from "./drain.js";
+import { type PrismRequestHandler } from "./types.js";
+export interface CreatePrismHealthHandlerOptions {
+    /** Path prefix. Default `/health`. Routes: `/livez`, `/readyz`, and prefix itself. */
+    readonly basePath?: string;
+    /** Liveness probe. Default always true. Must stay O(1)/bounded. */
+    readonly live?: () => boolean | Promise<boolean>;
+    /** Readiness probe (deps). Default true. Must stay O(1)/bounded. */
+    readonly ready?: () => boolean | Promise<boolean>;
+    readonly drain?: PrismDrainController;
+    /**
+     * Optional extra fields for `?detail=1`. Never include secrets/tenant payloads.
+     * Emitted only when `authorizeDetail` returns true.
+     */
+    readonly detail?: () => Readonly<Record<string, unknown>> | Promise<Readonly<Record<string, unknown>>>;
+    readonly authorizeDetail?: (request: Request) => boolean | Promise<boolean>;
+    readonly limits?: PrismDeploymentLimits;
+}
+export declare function createPrismHealthHandler(options?: CreatePrismHealthHandlerOptions): PrismRequestHandler;

package/dist/health.js

@@ -0,0 +1,103 @@
+import { resolvePrismDeploymentLimits, } from "./limits.js";
+import { PrismServerError } from "./types.js";
+const JSON_HEADERS = { "content-type": "application/json; charset=utf-8" };
+export function createPrismHealthHandler(options = {}) {
+    const limits = resolvePrismDeploymentLimits(options.limits);
+    const base = normalizeHealthBase(options.basePath ?? "/health");
+    return async (request) => {
+        try {
+            if (request.method !== "GET" && request.method !== "HEAD") {
+                throw new PrismServerError("Method not allowed", 405, "ERR_PRISM_SERVER_METHOD");
+            }
+            const url = new URL(request.url);
+            const path = url.pathname.replace(/\/$/, "") || "/";
+            const livePath = `${base}/livez`;
+            const readyPath = `${base}/readyz`;
+            if (path !== base && path !== livePath && path !== readyPath) {
+                throw new PrismServerError("Not found", 404, "ERR_PRISM_SERVER_NOT_FOUND");
+            }
+            const wantDetail = url.searchParams.get("detail") === "1";
+            if (wantDetail) {
+                const allowed = options.authorizeDetail ? await options.authorizeDetail(request) : false;
+                if (!allowed)
+                    throw new PrismServerError("Forbidden", 403, "ERR_PRISM_SERVER_FORBIDDEN");
+            }
+            const live = options.live ? await options.live() : true;
+            const readyCheck = options.ready ? await options.ready() : true;
+            const drainSnap = options.drain?.snapshot();
+            const draining = drainSnap?.draining === true;
+            const ready = readyCheck && !draining;
+            if (path === livePath) {
+                return healthJson({ status: live ? "ok" : "fail", live }, live ? 200 : 503, limits, request.method);
+            }
+            if (path === readyPath) {
+                return healthJson({
+                    status: ready ? "ok" : "fail",
+                    ready,
+                    ...(drainSnap ? { draining: drainSnap.draining } : {}),
+                }, ready ? 200 : 503, limits, request.method);
+            }
+            const body = {
+                status: live && ready ? "ok" : "fail",
+                live,
+                ready,
+            };
+            if (drainSnap) {
+                body.drain = {
+                    status: drainSnap.status,
+                    draining: drainSnap.draining,
+                    ...(drainSnap.deadlineAt === undefined ? {} : { deadlineAt: drainSnap.deadlineAt }),
+                };
+            }
+            if (wantDetail && options.detail) {
+                const extra = await options.detail();
+                assertSafeDetail(extra);
+                body.detail = extra;
+            }
+            const ok = live && ready;
+            return healthJson(body, ok ? 200 : 503, limits, request.method);
+        }
+        catch (error) {
+            if (error instanceof PrismServerError) {
+                return new Response(JSON.stringify({ error: { code: error.code, message: error.message } }), {
+                    status: error.status,
+                    headers: JSON_HEADERS,
+                });
+            }
+            return new Response(JSON.stringify({ error: { code: "ERR_PRISM_SERVER", message: "Health check failed" } }), {
+                status: 500,
+                headers: JSON_HEADERS,
+            });
+        }
+    };
+}
+function healthJson(body, status, limits, method) {
+    const text = JSON.stringify(body);
+    if (Buffer.byteLength(text, "utf8") > limits.maxHealthBytes) {
+        throw new PrismServerError("Health response too large", 507, "ERR_PRISM_SERVER_HEALTH_LIMIT");
+    }
+    if (method === "HEAD")
+        return new Response(null, { status, headers: JSON_HEADERS });
+    return new Response(text, { status, headers: JSON_HEADERS });
+}
+function normalizeHealthBase(basePath) {
+    if (!basePath.startsWith("/") || basePath.includes("?") || basePath.includes("#")) {
+        throw new PrismServerError("Invalid health basePath", 500, "ERR_PRISM_SERVER_CONFIG");
+    }
+    return basePath.replace(/\/$/, "") || "/health";
+}
+function assertSafeDetail(value) {
+    for (const key of Object.keys(value)) {
+        const lower = key.toLowerCase();
+        if (lower.includes("secret") ||
+            lower.includes("token") ||
+            lower.includes("password") ||
+            lower.includes("credential") ||
+            lower === "authorization" ||
+            lower === "prompt" ||
+            lower === "body") {
+            throw new PrismServerError("Health detail key not allowed", 500, "ERR_PRISM_SERVER_HEALTH_DETAIL");
+        }
+    }
+}
+//# sourceMappingURL=health.js.map

package/dist/index.d.ts

@@ -1,6 +1,16 @@
 export { createPrismHandler } from "./handler.js";
-export { DEFAULT_MAX_REQUEST_BYTES, HARD_MAX_REQUEST_BYTES, DEFAULT_MAX_RESPONSE_BYTES, HARD_MAX_RESPONSE_BYTES, DEFAULT_MAX_EVENT_BYTES, HARD_MAX_EVENT_BYTES, DEFAULT_MAX_STREAM_BYTES, HARD_MAX_STREAM_BYTES, DEFAULT_MAX_STREAM_EVENTS, HARD_MAX_STREAM_EVENTS, DEFAULT_MAX_CONCURRENT_RUNS, HARD_MAX_CONCURRENT_RUNS, DEFAULT_MAX_QUEUED_EVENTS, HARD_MAX_QUEUED_EVENTS, DEFAULT_REQUEST_TIMEOUT_MS, HARD_REQUEST_TIMEOUT_MS, resolvePrismServerLimits, } from "./limits.js";
-export type { PrismServerLimits, ResolvedPrismServerLimits, } from "./limits.js";
+export { createPrismDrainController, isAdmitOperation } from "./drain.js";
+export { createPrismHealthHandler } from "./health.js";
+export { createMemoryRateLimiter } from "./rate-limit.js";
+export { createPrismEventReplay, createPrismReplayHandler } from "./replay.js";
+export { createPrismDeploymentLease, PRISM_DEPLOYMENT_LEASE_NAMESPACE } from "./deployment.js";
+export { DEFAULT_MAX_REQUEST_BYTES, HARD_MAX_REQUEST_BYTES, DEFAULT_MAX_RESPONSE_BYTES, HARD_MAX_RESPONSE_BYTES, DEFAULT_MAX_EVENT_BYTES, HARD_MAX_EVENT_BYTES, DEFAULT_MAX_STREAM_BYTES, HARD_MAX_STREAM_BYTES, DEFAULT_MAX_STREAM_EVENTS, HARD_MAX_STREAM_EVENTS, DEFAULT_MAX_CONCURRENT_RUNS, HARD_MAX_CONCURRENT_RUNS, DEFAULT_MAX_QUEUED_EVENTS, HARD_MAX_QUEUED_EVENTS, DEFAULT_REQUEST_TIMEOUT_MS, HARD_REQUEST_TIMEOUT_MS, DEFAULT_MAX_HEALTH_BYTES, HARD_MAX_HEALTH_BYTES, DEFAULT_DRAIN_DEADLINE_MS, HARD_DRAIN_DEADLINE_MS, DEFAULT_MAX_REPLAY_EVENTS, HARD_MAX_REPLAY_EVENTS, DEFAULT_MAX_REPLAY_CURSOR_BYTES, HARD_MAX_REPLAY_CURSOR_BYTES, resolvePrismServerLimits, resolvePrismDeploymentLimits, } from "./limits.js";
+export type { PrismServerLimits, ResolvedPrismServerLimits, PrismDeploymentLimits, ResolvedPrismDeploymentLimits, } from "./limits.js";
 export type { PrismServerOperation, PrismServerAuthorization, PrismServerAuthorizationInput, PrismServerAuthorizer, PrismAgentExposure, PrismAgentRunExposure, PrismWorkflowExposure, PrismScheduleExposure, CreatePrismHandlerOptions, PrismRequestHandler, } from "./types.js";
+export type { PrismDrainController, PrismDrainControllerOptions, PrismDrainSnapshot } from "./drain.js";
+export type { CreatePrismHealthHandlerOptions } from "./health.js";
+export type { PrismServerRateLimiter, PrismServerRateLimitDenial, PrismServerRateLimitInput, MemoryRateLimiterOptions, } from "./rate-limit.js";
+export type { PrismEventReplay, PrismEventReplayRequest, CreatePrismEventReplayOptions, CreatePrismReplayHandlerOptions, } from "./replay.js";
+export type { PrismDeploymentLease, PrismDeploymentLeaseOptions } from "./deployment.js";
 export { PrismServerError } from "./types.js";
 export declare const packageName = "@arnilo/prism-server";

package/dist/index.js

@@ -1,5 +1,10 @@
 export { createPrismHandler } from "./handler.js";
-export { DEFAULT_MAX_REQUEST_BYTES, HARD_MAX_REQUEST_BYTES, DEFAULT_MAX_RESPONSE_BYTES, HARD_MAX_RESPONSE_BYTES, DEFAULT_MAX_EVENT_BYTES, HARD_MAX_EVENT_BYTES, DEFAULT_MAX_STREAM_BYTES, HARD_MAX_STREAM_BYTES, DEFAULT_MAX_STREAM_EVENTS, HARD_MAX_STREAM_EVENTS, DEFAULT_MAX_CONCURRENT_RUNS, HARD_MAX_CONCURRENT_RUNS, DEFAULT_MAX_QUEUED_EVENTS, HARD_MAX_QUEUED_EVENTS, DEFAULT_REQUEST_TIMEOUT_MS, HARD_REQUEST_TIMEOUT_MS, resolvePrismServerLimits, } from "./limits.js";
+export { createPrismDrainController, isAdmitOperation } from "./drain.js";
+export { createPrismHealthHandler } from "./health.js";
+export { createMemoryRateLimiter } from "./rate-limit.js";
+export { createPrismEventReplay, createPrismReplayHandler } from "./replay.js";
+export { createPrismDeploymentLease, PRISM_DEPLOYMENT_LEASE_NAMESPACE } from "./deployment.js";
+export { DEFAULT_MAX_REQUEST_BYTES, HARD_MAX_REQUEST_BYTES, DEFAULT_MAX_RESPONSE_BYTES, HARD_MAX_RESPONSE_BYTES, DEFAULT_MAX_EVENT_BYTES, HARD_MAX_EVENT_BYTES, DEFAULT_MAX_STREAM_BYTES, HARD_MAX_STREAM_BYTES, DEFAULT_MAX_STREAM_EVENTS, HARD_MAX_STREAM_EVENTS, DEFAULT_MAX_CONCURRENT_RUNS, HARD_MAX_CONCURRENT_RUNS, DEFAULT_MAX_QUEUED_EVENTS, HARD_MAX_QUEUED_EVENTS, DEFAULT_REQUEST_TIMEOUT_MS, HARD_REQUEST_TIMEOUT_MS, DEFAULT_MAX_HEALTH_BYTES, HARD_MAX_HEALTH_BYTES, DEFAULT_DRAIN_DEADLINE_MS, HARD_DRAIN_DEADLINE_MS, DEFAULT_MAX_REPLAY_EVENTS, HARD_MAX_REPLAY_EVENTS, DEFAULT_MAX_REPLAY_CURSOR_BYTES, HARD_MAX_REPLAY_CURSOR_BYTES, resolvePrismServerLimits, resolvePrismDeploymentLimits, } from "./limits.js";
 export { PrismServerError } from "./types.js";
 export const packageName = "@arnilo/prism-server";
 //# sourceMappingURL=index.js.map

package/dist/limits.d.ts

@@ -14,6 +14,15 @@ export declare const DEFAULT_MAX_QUEUED_EVENTS = 128;
 export declare const HARD_MAX_QUEUED_EVENTS = 4096;
 export declare const DEFAULT_REQUEST_TIMEOUT_MS = 120000;
 export declare const HARD_REQUEST_TIMEOUT_MS: number;
+/** Phase 8 freeze: health body 4 KiB / 64 KiB; drain deadline 30 s / 5 min; replay page 100 / 500; cursor 4 / 16 KiB. */
+export declare const DEFAULT_MAX_HEALTH_BYTES: number;
+export declare const HARD_MAX_HEALTH_BYTES: number;
+export declare const DEFAULT_DRAIN_DEADLINE_MS = 30000;
+export declare const HARD_DRAIN_DEADLINE_MS: number;
+export declare const DEFAULT_MAX_REPLAY_EVENTS = 100;
+export declare const HARD_MAX_REPLAY_EVENTS = 500;
+export declare const DEFAULT_MAX_REPLAY_CURSOR_BYTES: number;
+export declare const HARD_MAX_REPLAY_CURSOR_BYTES: number;
 export interface PrismServerLimits {
     readonly maxRequestBytes?: number;
     readonly maxResponseBytes?: number;
@@ -34,4 +43,17 @@ export interface ResolvedPrismServerLimits {
     readonly maxQueuedEvents: number;
     readonly requestTimeoutMs: number;
 }
+export interface PrismDeploymentLimits {
+    readonly maxHealthBytes?: number;
+    readonly drainDeadlineMs?: number;
+    readonly maxReplayEvents?: number;
+    readonly maxReplayCursorBytes?: number;
+}
+export interface ResolvedPrismDeploymentLimits {
+    readonly maxHealthBytes: number;
+    readonly drainDeadlineMs: number;
+    readonly maxReplayEvents: number;
+    readonly maxReplayCursorBytes: number;
+}
 export declare function resolvePrismServerLimits(input?: PrismServerLimits): ResolvedPrismServerLimits;
+export declare function resolvePrismDeploymentLimits(input?: PrismDeploymentLimits): ResolvedPrismDeploymentLimits;

package/dist/limits.js

@@ -14,6 +14,15 @@ export const DEFAULT_MAX_QUEUED_EVENTS = 128;
 export const HARD_MAX_QUEUED_EVENTS = 4096;
 export const DEFAULT_REQUEST_TIMEOUT_MS = 120_000;
 export const HARD_REQUEST_TIMEOUT_MS = 30 * 60_000;
+/** Phase 8 freeze: health body 4 KiB / 64 KiB; drain deadline 30 s / 5 min; replay page 100 / 500; cursor 4 / 16 KiB. */
+export const DEFAULT_MAX_HEALTH_BYTES = 4 * 1024;
+export const HARD_MAX_HEALTH_BYTES = 64 * 1024;
+export const DEFAULT_DRAIN_DEADLINE_MS = 30_000;
+export const HARD_DRAIN_DEADLINE_MS = 5 * 60_000;
+export const DEFAULT_MAX_REPLAY_EVENTS = 100;
+export const HARD_MAX_REPLAY_EVENTS = 500;
+export const DEFAULT_MAX_REPLAY_CURSOR_BYTES = 4 * 1024;
+export const HARD_MAX_REPLAY_CURSOR_BYTES = 16 * 1024;
 export function resolvePrismServerLimits(input = {}) {
     return {
         maxRequestBytes: bounded(input.maxRequestBytes, DEFAULT_MAX_REQUEST_BYTES, HARD_MAX_REQUEST_BYTES, "maxRequestBytes"),
@@ -26,6 +35,14 @@ export function resolvePrismServerLimits(input = {}) {
         requestTimeoutMs: bounded(input.requestTimeoutMs, DEFAULT_REQUEST_TIMEOUT_MS, HARD_REQUEST_TIMEOUT_MS, "requestTimeoutMs"),
     };
 }
+export function resolvePrismDeploymentLimits(input = {}) {
+    return {
+        maxHealthBytes: bounded(input.maxHealthBytes, DEFAULT_MAX_HEALTH_BYTES, HARD_MAX_HEALTH_BYTES, "maxHealthBytes"),
+        drainDeadlineMs: bounded(input.drainDeadlineMs, DEFAULT_DRAIN_DEADLINE_MS, HARD_DRAIN_DEADLINE_MS, "drainDeadlineMs"),
+        maxReplayEvents: bounded(input.maxReplayEvents, DEFAULT_MAX_REPLAY_EVENTS, HARD_MAX_REPLAY_EVENTS, "maxReplayEvents"),
+        maxReplayCursorBytes: bounded(input.maxReplayCursorBytes, DEFAULT_MAX_REPLAY_CURSOR_BYTES, HARD_MAX_REPLAY_CURSOR_BYTES, "maxReplayCursorBytes"),
+    };
+}
 function bounded(value, fallback, cap, name) {
     const resolved = value ?? fallback;
     if (!Number.isSafeInteger(resolved) || resolved < 1 || resolved > cap) {

package/dist/rate-limit.d.ts

@@ -0,0 +1,26 @@
+import type { PrismServerAuthorization, PrismServerOperation } from "./types.js";
+export interface PrismServerRateLimitDenial {
+    readonly retryAfterMs?: number;
+    /** Attributable denial code for hosts/logs. Default ERR_PRISM_SERVER_RATE_LIMIT. */
+    readonly code?: string;
+    readonly message?: string;
+}
+export interface PrismServerRateLimitInput {
+    readonly request: Request;
+    readonly operation: PrismServerOperation;
+    readonly capabilityId: string;
+    readonly authorization: PrismServerAuthorization;
+    readonly signal: AbortSignal;
+}
+/** Return `true` to admit; return a denial object to short-circuit with 429. */
+export type PrismServerRateLimiter = (input: PrismServerRateLimitInput) => true | PrismServerRateLimitDenial | Promise<true | PrismServerRateLimitDenial>;
+export interface MemoryRateLimiterOptions {
+    readonly maxRequests: number;
+    readonly windowMs: number;
+    /** Default: identity tenant/account/user + operation. */
+    readonly key?: (input: PrismServerRateLimitInput) => string;
+    /** Cap distinct keys retained (oldest eviction). Default 1024. */
+    readonly maxKeys?: number;
+}
+/** Tiny in-memory sliding window for tests/single-process hosts. Not a distributed limiter. */
+export declare function createMemoryRateLimiter(options: MemoryRateLimiterOptions): PrismServerRateLimiter;

package/dist/rate-limit.js

@@ -0,0 +1,41 @@
+/** Tiny in-memory sliding window for tests/single-process hosts. Not a distributed limiter. */
+export function createMemoryRateLimiter(options) {
+    if (!Number.isSafeInteger(options.maxRequests) || options.maxRequests < 1) {
+        throw new RangeError("maxRequests must be a positive safe integer");
+    }
+    if (!Number.isSafeInteger(options.windowMs) || options.windowMs < 1) {
+        throw new RangeError("windowMs must be a positive safe integer");
+    }
+    const maxKeys = options.maxKeys ?? 1024;
+    if (!Number.isSafeInteger(maxKeys) || maxKeys < 1)
+        throw new RangeError("maxKeys must be a positive safe integer");
+    const buckets = new Map();
+    return (input) => {
+        input.signal.throwIfAborted();
+        const key = options.key?.(input) ?? defaultKey(input);
+        const now = Date.now();
+        const windowStart = now - options.windowMs;
+        let stamps = (buckets.get(key) ?? []).filter((t) => t > windowStart);
+        if (stamps.length >= options.maxRequests) {
+            const oldest = stamps[0] ?? now;
+            return {
+                retryAfterMs: Math.max(1, oldest + options.windowMs - now),
+                code: "ERR_PRISM_SERVER_RATE_LIMIT",
+                message: "Rate limit exceeded",
+            };
+        }
+        stamps = [...stamps, now];
+        if (!buckets.has(key) && buckets.size >= maxKeys) {
+            const first = buckets.keys().next().value;
+            if (first !== undefined)
+                buckets.delete(first);
+        }
+        buckets.set(key, stamps);
+        return true;
+    };
+}
+function defaultKey(input) {
+    const o = input.authorization.ownership;
+    return `${o.tenantId ?? ""}\0${o.accountId ?? ""}\0${o.userId ?? ""}\0${input.operation}\0${input.capabilityId}`;
+}
+//# sourceMappingURL=rate-limit.js.map

package/dist/replay.d.ts

@@ -0,0 +1,25 @@
+import type { AgentEventRecord, OwnershipScope, PersistencePage, ProductionPersistenceStore } from "@arnilo/prism";
+import { type PrismDeploymentLimits } from "./limits.js";
+export interface PrismEventReplayRequest {
+    readonly ownership: OwnershipScope;
+    readonly sessionId: string;
+    readonly runId: string;
+    readonly cursor?: string;
+    readonly signal?: AbortSignal;
+}
+export interface PrismEventReplay {
+    page(input: PrismEventReplayRequest): Promise<PersistencePage<AgentEventRecord>>;
+}
+export interface CreatePrismEventReplayOptions {
+    readonly limits?: PrismDeploymentLimits;
+}
+/** Ownership-scoped, cursor-paginated durable event replay. Does not re-run work. */
+export declare function createPrismEventReplay(store: Pick<ProductionPersistenceStore, "queryEvents">, options?: CreatePrismEventReplayOptions): PrismEventReplay;
+export interface CreatePrismReplayHandlerOptions {
+    readonly replay: PrismEventReplay;
+    readonly authorize: (request: Request) => false | OwnershipScope | Promise<false | OwnershipScope>;
+    readonly basePath?: string;
+    readonly limits?: PrismDeploymentLimits;
+}
+/** Optional HTTP adapter: POST `{ sessionId, runId, cursor? }` → ownership-scoped page. */
+export declare function createPrismReplayHandler(options: CreatePrismReplayHandlerOptions): import("./types.js").PrismRequestHandler;

package/dist/replay.js

@@ -0,0 +1,116 @@
+import { resolvePrismDeploymentLimits, } from "./limits.js";
+import { PrismServerError } from "./types.js";
+/** Ownership-scoped, cursor-paginated durable event replay. Does not re-run work. */
+export function createPrismEventReplay(store, options = {}) {
+    const limits = resolvePrismDeploymentLimits(options.limits);
+    return {
+        async page(input) {
+            input.signal?.throwIfAborted();
+            assertOwnership(input.ownership);
+            if (!input.sessionId || !input.runId) {
+                throw new PrismServerError("sessionId and runId are required", 400, "ERR_PRISM_SERVER_REPLAY");
+            }
+            if (input.cursor !== undefined)
+                assertCursor(input.cursor, limits);
+            const page = await store.queryEvents({
+                sessionId: input.sessionId,
+                runId: input.runId,
+                cursor: input.cursor,
+                limit: limits.maxReplayEvents,
+                order: "asc",
+                redacted: true,
+                ...input.ownership,
+            });
+            if (page.items.length > limits.maxReplayEvents) {
+                throw new PrismServerError("Replay page exceeds limit", 507, "ERR_PRISM_SERVER_REPLAY_LIMIT");
+            }
+            if (page.items.some((record) => !record.redacted)) {
+                throw new PrismServerError("Replay page must be redacted", 500, "ERR_PRISM_SERVER_REPLAY");
+            }
+            if (page.nextCursor !== undefined)
+                assertCursor(page.nextCursor, limits);
+            return page;
+        },
+    };
+}
+/** Optional HTTP adapter: POST `{ sessionId, runId, cursor? }` → ownership-scoped page. */
+export function createPrismReplayHandler(options) {
+    const base = (options.basePath ?? "/prism/replay/events").replace(/\/$/, "");
+    const limits = resolvePrismDeploymentLimits(options.limits);
+    return async (request) => {
+        try {
+            if (request.method !== "POST") {
+                throw new PrismServerError("Method not allowed", 405, "ERR_PRISM_SERVER_METHOD");
+            }
+            const path = new URL(request.url).pathname.replace(/\/$/, "");
+            if (path !== base)
+                throw new PrismServerError("Not found", 404, "ERR_PRISM_SERVER_NOT_FOUND");
+            const ownership = await options.authorize(request);
+            if (!ownership)
+                throw new PrismServerError("Forbidden", 403, "ERR_PRISM_SERVER_FORBIDDEN");
+            assertOwnership(ownership);
+            const body = await readSmallJson(request, limits.maxReplayCursorBytes + 1024);
+            const page = await options.replay.page({
+                ownership,
+                sessionId: readId(body.sessionId, "sessionId"),
+                runId: readId(body.runId, "runId"),
+                cursor: body.cursor === undefined ? undefined : readCursor(body.cursor, limits),
+                signal: request.signal,
+            });
+            return new Response(JSON.stringify(page), {
+                status: 200,
+                headers: { "content-type": "application/json; charset=utf-8" },
+            });
+        }
+        catch (error) {
+            if (error instanceof PrismServerError) {
+                return new Response(JSON.stringify({ error: { code: error.code, message: error.message } }), {
+                    status: error.status,
+                    headers: { "content-type": "application/json; charset=utf-8" },
+                });
+            }
+            return new Response(JSON.stringify({ error: { code: "ERR_PRISM_SERVER", message: "Replay failed" } }), {
+                status: 500,
+                headers: { "content-type": "application/json; charset=utf-8" },
+            });
+        }
+    };
+}
+function assertOwnership(ownership) {
+    if (![ownership.tenantId, ownership.accountId, ownership.userId].some((v) => typeof v === "string" && v.length > 0)) {
+        throw new PrismServerError("Forbidden", 403, "ERR_PRISM_SERVER_FORBIDDEN");
+    }
+}
+function assertCursor(cursor, limits) {
+    if (typeof cursor !== "string" || Buffer.byteLength(cursor, "utf8") > limits.maxReplayCursorBytes) {
+        throw new PrismServerError("Replay cursor exceeds limit", 400, "ERR_PRISM_SERVER_REPLAY_CURSOR");
+    }
+}
+function readCursor(value, limits) {
+    if (typeof value !== "string")
+        throw new PrismServerError("cursor must be a string", 400, "ERR_PRISM_SERVER_BODY");
+    assertCursor(value, limits);
+    return value;
+}
+function readId(value, name) {
+    if (typeof value !== "string" || !value || value.length > 128 || !/^[A-Za-z0-9._:-]+$/.test(value)) {
+        throw new PrismServerError(`Invalid ${name}`, 400, "ERR_PRISM_SERVER_BODY");
+    }
+    return value;
+}
+async function readSmallJson(request, maxBytes) {
+    const text = await request.text();
+    if (Buffer.byteLength(text, "utf8") > maxBytes) {
+        throw new PrismServerError("Request body too large", 413, "ERR_PRISM_SERVER_BODY_LIMIT");
+    }
+    try {
+        const value = JSON.parse(text);
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            throw new Error("object");
+        return value;
+    }
+    catch {
+        throw new PrismServerError("Invalid JSON object body", 400, "ERR_PRISM_SERVER_BODY");
+    }
+}
+//# sourceMappingURL=replay.js.map

package/dist/types.d.ts

@@ -1,9 +1,13 @@
-import type { Agent, AgentRunLifecycle, AgentSession, OwnershipScope, RunOptions, SecretRedactor } from "@arnilo/prism";
+import type { Agent, AgentIdentity, AgentRunLifecycle, AgentSession, OwnershipScope, RunOptions, SecretRedactor } from "@arnilo/prism";
 import type { RunWorkflowOptions, WorkflowCheckpointAdapter, WorkflowDefinition, WorkflowSchedules } from "@arnilo/prism-workflows";
+import type { PrismDrainController } from "./drain.js";
 import type { PrismServerLimits } from "./limits.js";
+import type { PrismServerRateLimiter } from "./rate-limit.js";
 export type PrismServerOperation = "agent.run" | "agent.stream" | "agent.status" | "agent.resume" | "workflow.run" | "workflow.stream" | "workflow.status" | "workflow.cancel" | "workflow.resume" | "workflow.enqueue" | "workflow.replay" | "schedule.create" | "schedule.list" | "schedule.pause" | "schedule.resume" | "schedule.trigger" | "schedule.delete";
 export interface PrismServerAuthorization {
     readonly ownership: OwnershipScope;
+    /** Host-verified identity; when set must project onto `ownership` without widening. */
+    readonly identity?: AgentIdentity;
     readonly metadata?: Readonly<Record<string, unknown>>;
 }
 export interface PrismServerAuthorizationInput {
@@ -40,10 +44,15 @@ export interface CreatePrismHandlerOptions {
     readonly redactor?: SecretRedactor;
     readonly limits?: PrismServerLimits;
     readonly disconnectAborts?: boolean;
+    /** Optional graceful drain; blocks admit operations with 503 while draining. */
+    readonly drain?: PrismDrainController;
+    /** Optional host rate-limit adapter; runs after authorize, before admit/session create. */
+    readonly rateLimit?: PrismServerRateLimiter;
 }
 export type PrismRequestHandler = (request: Request) => Promise<Response>;
 export declare class PrismServerError extends Error {
     readonly status: number;
     readonly code: string;
-    constructor(message: string, status?: number, code?: string);
+    readonly headers?: Readonly<Record<string, string>> | undefined;
+    constructor(message: string, status?: number, code?: string, headers?: Readonly<Record<string, string>> | undefined);
 }

package/dist/types.js

@@ -1,10 +1,12 @@
 export class PrismServerError extends Error {
     status;
     code;
-    constructor(message, status = 500, code = "ERR_PRISM_SERVER") {
+    headers;
+    constructor(message, status = 500, code = "ERR_PRISM_SERVER", headers) {
         super(message);
         this.status = status;
         this.code = code;
+        this.headers = headers;
         this.name = "PrismServerError";
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arnilo/prism-server",
-  "version": "0.0.12",
+  "version": "0.0.13",
   "description": "Optional framework-free Web Request-to-Response handler for explicitly selected Prism agents and workflows.",
   "type": "module",
   "main": "./dist/index.js",
@@ -25,8 +25,8 @@
     "pack:dry-run": "npm pack --dry-run"
   },
   "peerDependencies": {
-    "@arnilo/prism": "0.0.12",
-    "@arnilo/prism-workflows": "0.0.12"
+    "@arnilo/prism": "0.0.13",
+    "@arnilo/prism-workflows": "0.0.13"
   },
   "devDependencies": {
     "@arnilo/prism": "file:../..",