@danypops/jittor 0.9.0 → 0.11.0

package/src/router.ts

@@ -1,3 +1,4 @@
+import { ROUTER_MAX_SESSION_SCOPES, ROUTER_SESSION_ID_MAX_CHARACTERS } from "./constants.ts";
 import type { MetricStore } from "./ports/metric-store.ts";
 import type { RouteOverride, RouterController, RouterStatus, TelemetryPollResult, TelemetrySourceStatus } from "./ports/router-controller.ts";
 import type { TelemetrySource } from "./ports/telemetry-source.ts";
@@ -22,22 +23,37 @@ function sameRoute(left: Route, right: Route): boolean {
 	return left.provider === right.provider && left.model === right.model && left.thinking === right.thinking;
 }
 
+const GLOBAL_ROUTER_SCOPE = "global";
+
+interface RouterSessionState {
+	currentRoute: Route;
+	availableRoutes: Route[];
+	lastDecision: PolicyDecision | null;
+	previousPolicyDecision: PolicyDecision | null;
+	paused: boolean;
+	override: RouteOverride | null;
+	lastAccess: number;
+}
+
+function routerScope(sessionId: string | undefined): string {
+	if (sessionId === undefined) return GLOBAL_ROUTER_SCOPE;
+	if (sessionId.length === 0 || sessionId.length > ROUTER_SESSION_ID_MAX_CHARACTERS) {
+		throw new Error(`session_id must contain 1-${ROUTER_SESSION_ID_MAX_CHARACTERS} characters`);
+	}
+	return sessionId;
+}
+
 export class JittorRouter implements RouterController {
 	private readonly clock: () => number;
 	private readonly windows = new Map<string, BudgetWindow[]>();
+	private readonly sessions = new Map<string, RouterSessionState>();
 	private sourceStatuses: TelemetrySourceStatus[] = [];
-	private lastDecision: PolicyDecision | null = null;
-	private previousPolicyDecision: PolicyDecision | null = null;
-	private paused = false;
-	private override: RouteOverride | null = null;
 	private inFlightPoll: Promise<TelemetryPollResult> | null = null;
-	private currentRoute: Route;
-	private availableRoutes: Route[];
+	private accessSequence = 0;
 
 	constructor(private readonly options: JittorRouterOptions) {
 		this.clock = options.clock ?? Date.now;
-		this.currentRoute = options.currentRoute;
-		this.availableRoutes = structuredClone(options.routes);
+		this.sessions.set(GLOBAL_ROUTER_SCOPE, this.newSessionState());
 	}
 
 	poll(): Promise<TelemetryPollResult> {
@@ -45,91 +61,102 @@ export class JittorRouter implements RouterController {
 		return this.inFlightPoll;
 	}
 
-	status(): RouterStatus {
-		this.expireOverride();
+	status(sessionId?: string): RouterStatus {
+		const state = this.sessionState(sessionId);
+		this.expireOverride(state);
 		return {
-			ready: this.isReady(),
-			paused: this.paused,
+			ready: this.isReady(state),
+			paused: state.paused,
 			sources: structuredClone(this.sourceStatuses),
-			lastDecision: this.lastDecision ? structuredClone(this.lastDecision) : null,
-			override: this.override ? structuredClone(this.override) : null,
-			currentRoute: structuredClone(this.currentRoute),
-			availableRoutes: structuredClone(this.availableRoutes),
+			lastDecision: state.lastDecision ? structuredClone(state.lastDecision) : null,
+			override: state.override ? structuredClone(state.override) : null,
+			currentRoute: structuredClone(state.currentRoute),
+			availableRoutes: structuredClone(state.availableRoutes),
 		};
 	}
 
-	decide(): PolicyDecision {
+	decide(sessionId?: string): PolicyDecision {
 		const now = this.clock();
-		this.expireOverride();
-		if (this.paused) return this.remember({ action: "halt", pressure: Number.POSITIVE_INFINITY, reason: "Jittor is paused", decidedAt: now, trace: ["manual pause"] });
-		if (this.override) {
-			const route = this.override.route;
-			const action = route.provider !== this.currentRoute.provider
+		const state = this.sessionState(sessionId);
+		this.expireOverride(state);
+		if (state.paused) return this.remember(state, { action: "halt", pressure: Number.POSITIVE_INFINITY, reason: "Jittor is paused", decidedAt: now, trace: ["manual pause"] });
+		if (state.override) {
+			const route = state.override.route;
+			const action = route.provider !== state.currentRoute.provider
 				? "switch-provider"
-				: route.model !== this.currentRoute.model
+				: route.model !== state.currentRoute.model
 					? "switch-model"
-					: route.thinking !== this.currentRoute.thinking ? "lower-thinking" : "continue";
-			return this.remember({ action, route, pressure: 0, reason: "manual route override", decidedAt: now, trace: ["manual override"] });
+					: route.thinking !== state.currentRoute.thinking ? "lower-thinking" : "continue";
+			return this.remember(state, { action, route, pressure: 0, reason: "manual route override", decidedAt: now, trace: ["manual override"] });
+		}
+		if (!this.isReady(state)) return this.remember(state, { action: "halt", pressure: Number.POSITIVE_INFINITY, reason: "required telemetry is not ready", decidedAt: now, trace: ["fail closed"] });
+		const activeSources = this.options.sources.filter((source) => source.provider === state.currentRoute.provider);
+		const activeSourceIds = new Set(activeSources.map((source) => source.id));
+		const requiredSourceIds = new Set(activeSources.filter((source) => source.required).map((source) => source.id));
+		const activeWindows = [...this.windows.entries()].filter(([sourceId]) => activeSourceIds.has(sourceId));
+		const requiredWindows = activeWindows.filter(([sourceId]) => requiredSourceIds.has(sourceId)).flatMap(([, windows]) => windows);
+		if (requiredSourceIds.size === 0 && activeWindows.every(([, windows]) => windows.length === 0)) {
+			return this.rememberPolicy(state, { action: "continue", pressure: 0, reason: "provider has no enforceable budget window; monitor-only", decidedAt: now, trace: ["monitor-only"] });
 		}
-		if (!this.isReady()) return this.remember({ action: "halt", pressure: Number.POSITIVE_INFINITY, reason: "required telemetry is not ready", decidedAt: now, trace: ["fail closed"] });
-		const activeSourceIds = new Set(this.options.sources.filter((source) => source.provider === this.currentRoute.provider).map((source) => source.id));
-		return this.rememberPolicy(evaluateRoutingPolicy({
+		return this.rememberPolicy(state, evaluateRoutingPolicy({
 			now,
-			windows: [...this.windows.entries()].filter(([sourceId]) => activeSourceIds.has(sourceId)).flatMap(([, windows]) => windows),
-			currentRoute: this.currentRoute,
-			routes: this.availableRoutes,
+			windows: requiredSourceIds.size > 0 && requiredWindows.length === 0 ? [] : activeWindows.flatMap(([, windows]) => windows),
+			currentRoute: state.currentRoute,
+			routes: state.availableRoutes,
 			config: this.options.policy,
-			previousDecision: this.previousPolicyDecision ?? undefined,
+			previousDecision: state.previousPolicyDecision ?? undefined,
 		}));
 	}
 
-	pause(): RouterStatus {
-		this.paused = true;
-		return this.status();
+	pause(sessionId?: string): RouterStatus {
+		this.sessionState(sessionId).paused = true;
+		return this.status(sessionId);
 	}
 
-	resume(): RouterStatus {
-		this.paused = false;
-		return this.status();
+	resume(sessionId?: string): RouterStatus {
+		this.sessionState(sessionId).paused = false;
+		return this.status(sessionId);
 	}
 
-	setOverride(override?: RouteOverride): RouterStatus {
-		if (!override || !this.availableRoutes.some((route) => sameRoute(route, override.route))) throw new Error("override route is not available in Pi");
+	setOverride(override: RouteOverride | undefined, sessionId?: string): RouterStatus {
+		const state = this.sessionState(sessionId);
+		if (!override || !state.availableRoutes.some((route) => sameRoute(route, override.route))) throw new Error("override route is not available in Pi");
 		if (override.expiresAt !== null && override.expiresAt <= this.clock()) throw new Error("override expiry must be in the future");
-		this.override = structuredClone(override);
-		return this.status();
+		state.override = structuredClone(override);
+		return this.status(sessionId);
 	}
 
-	clearOverride(): RouterStatus {
-		this.override = null;
-		return this.status();
+	clearOverride(sessionId?: string): RouterStatus {
+		this.sessionState(sessionId).override = null;
+		return this.status(sessionId);
 	}
 
-	setCurrentRoute(route: Route): RouterStatus {
+	setCurrentRoute(route: Route, sessionId?: string): RouterStatus {
 		if (!route.provider || !route.model || !route.thinking) throw new Error("current route is incomplete");
-		this.currentRoute = structuredClone(route);
-		return this.status();
+		this.sessionState(sessionId).currentRoute = structuredClone(route);
+		return this.status(sessionId);
 	}
 
-	setAvailableRoutes(routes: Route[]): RouterStatus {
+	setAvailableRoutes(routes: Route[], sessionId?: string): RouterStatus {
 		if (!Array.isArray(routes)) throw new Error("available routes must be an array");
 		const valid = routes.filter((route) => typeof route?.provider === "string" && route.provider.length > 0
 			&& typeof route.model === "string" && route.model.length > 0
 			&& typeof route.thinking === "string" && route.thinking.length > 0);
-		this.availableRoutes = valid.filter((route, index) => valid.findIndex((candidate) => sameRoute(candidate, route)) === index).map((route) => structuredClone(route));
-		return this.status();
+		this.sessionState(sessionId).availableRoutes = valid.filter((route, index) => valid.findIndex((candidate) => sameRoute(candidate, route)) === index).map((route) => structuredClone(route));
+		return this.status(sessionId);
 	}
 
-	applyModelRanking(candidates: Route[]): RouterStatus {
+	applyModelRanking(candidates: Route[], sessionId?: string): RouterStatus {
 		if (!Array.isArray(candidates) || candidates.length === 0) throw new Error("model ranking must contain candidates");
+		const state = this.sessionState(sessionId);
 		const ranked = candidates
 			.filter((candidate, index) => candidates.findIndex((other) => sameRoute(other, candidate)) === index)
-			.map((candidate) => this.availableRoutes.find((route) => sameRoute(route, candidate)))
+			.map((candidate) => state.availableRoutes.find((route) => sameRoute(route, candidate)))
 			.filter((route): route is Route => route !== undefined);
-		const current = ranked.find((route) => sameRoute(route, this.currentRoute));
+		const current = ranked.find((route) => sameRoute(route, state.currentRoute));
 		if (!current) throw new Error("model ranking does not contain the current available route");
-		this.availableRoutes = [structuredClone(current), ...ranked.filter((route) => !sameRoute(route, current)).map((route) => structuredClone(route))];
-		return this.status();
+		state.availableRoutes = [structuredClone(current), ...ranked.filter((route) => !sameRoute(route, current)).map((route) => structuredClone(route))];
+		return this.status(sessionId);
 	}
 
 	private async runPoll(): Promise<TelemetryPollResult> {
@@ -148,23 +175,53 @@ export class JittorRouter implements RouterController {
 		return { sources: structuredClone(statuses), observedAt: this.clock() };
 	}
 
-	private isReady(): boolean {
-		const active = this.options.sources.filter((source) => source.provider === this.currentRoute.provider);
-		if (active.length === 0) return false;
-		return active.every((source) => this.sourceStatuses.some((status) => status.id === source.id && status.ok));
+	private newSessionState(): RouterSessionState {
+		return {
+			currentRoute: structuredClone(this.options.currentRoute),
+			availableRoutes: structuredClone(this.options.routes),
+			lastDecision: null,
+			previousPolicyDecision: null,
+			paused: false,
+			override: null,
+			lastAccess: ++this.accessSequence,
+		};
+	}
+
+	private sessionState(sessionId?: string): RouterSessionState {
+		const scope = routerScope(sessionId);
+		const existing = this.sessions.get(scope);
+		if (existing) {
+			existing.lastAccess = ++this.accessSequence;
+			return existing;
+		}
+		if (this.sessions.size >= ROUTER_MAX_SESSION_SCOPES) {
+			const oldest = [...this.sessions.entries()]
+				.filter(([key]) => key !== GLOBAL_ROUTER_SCOPE)
+				.sort((left, right) => left[1].lastAccess - right[1].lastAccess)[0];
+			if (oldest) this.sessions.delete(oldest[0]);
+		}
+		const created = this.newSessionState();
+		this.sessions.set(scope, created);
+		return created;
+	}
+
+	private isReady(state: RouterSessionState): boolean {
+		if (state.availableRoutes.length === 0) return false;
+		const required = this.options.sources.filter((source) => source.provider === state.currentRoute.provider && source.required);
+		return required.every((source) => this.sourceStatuses.some((status) => status.id === source.id && status.ok));
 	}
 
-	private expireOverride(): void {
-		if (this.override?.expiresAt !== null && this.override && this.override.expiresAt <= this.clock()) this.override = null;
+	private expireOverride(state: RouterSessionState): void {
+		if (state.override?.expiresAt !== null && state.override && state.override.expiresAt <= this.clock()) state.override = null;
 	}
 
-	private remember(decision: PolicyDecision): PolicyDecision {
-		this.lastDecision = decision;
+	private remember(state: RouterSessionState, decision: PolicyDecision): PolicyDecision {
+		state.lastDecision = decision;
 		return structuredClone(decision);
 	}
 
-	private rememberPolicy(decision: PolicyDecision): PolicyDecision {
-		this.previousPolicyDecision = decision;
-		return this.remember(decision);
+	private rememberPolicy(state: RouterSessionState, decision: PolicyDecision): PolicyDecision {
+		state.previousPolicyDecision = decision;
+		return this.remember(state, decision);
 	}
 }

package/src/service.ts

@@ -1,9 +1,10 @@
 import { errorResponse, healthResponse, readyResponse, requireBearerToken } from "@danypops/daemon-kit/http";
-import { COMPACTION_DURATION_ESTIMATE_MAX_SAMPLES, CONTEXT_ASSESSMENT_DEFAULT_WINDOW_MS, CONTEXT_ASSESSMENT_QUERY_LIMIT, MAX_USAGE_BUCKETS, PRUNE_MIN_AGE_MS, SERVICE_MAX_BODY_BYTES, SERVICE_MAX_RESPONSE_BYTES, TASK_COST_QUERY_LIMIT, USAGE_MAX_DISTINCT_SCOPES } from "./constants.ts";
+import { SERVICE_MAX_BODY_BYTES, SERVICE_MAX_RESPONSE_BYTES } from "./constants.ts";
+import { InvalidSessionSecretError, SessionIdentity, type RegisterSessionIdentityResult } from "./session-identity-service.ts";
 import { VERSION } from "./version.ts";
-import { validateMetricObservation, type MetricObservation, type MetricQuery, type StoredMetricObservation } from "./domain/metric.ts";
-import { assessContextTelemetry, estimateCompactionDuration, type CompactionDurationEstimate, type ContextAssessment } from "./domain/context-telemetry.ts";
-import { buildTaskCostSummary, type TaskCostSummary } from "./domain/task-cost.ts";
+import type { MetricObservation, MetricQuery, StoredMetricObservation } from "./domain/metric.ts";
+import type { CompactionDurationEstimate, ContextAssessment } from "./domain/context-telemetry.ts";
+import type { TaskCostSummary } from "./domain/task-cost.ts";
 import type { UsageAggregateRow } from "./domain/usage.ts";
 import type { BenchmarkQuery, BenchmarkQueryResult, BenchmarkRefreshResult } from "./domain/benchmark.ts";
 import type { ModelRanker, ModelRecommendationInput } from "./domain/model-ranking-service.ts";
@@ -12,9 +13,18 @@ import type { BenchmarkController } from "./ports/benchmark-controller.ts";
 import type { MetricStore } from "./ports/metric-store.ts";
 import type { RouteOverride, RouterController, RouterStatus, TelemetryPollResult } from "./ports/router-controller.ts";
 import type { PolicyDecision, Route } from "./policy.ts";
+import { metricsOperations } from "./operations/metrics-operations.ts";
+import { benchmarkOperations } from "./operations/benchmark-operations.ts";
+import { contextOperations } from "./operations/context-operations.ts";
+import { routerOperations } from "./operations/router-operations.ts";
+import { modelRankingOperations } from "./operations/model-ranking-operations.ts";
+import { sessionIdentityOperations } from "./operations/session-identity-operations.ts";
+import { routerMutationAuthorizer } from "./operations/session-scope.ts";
+import type { OperationHandlerMap } from "./operations/types.ts";
 
 export const EXPECTED_OPERATION_NAMES = [
 	"metrics.record",
+	"metrics.record_batch",
 	"metrics.query",
 	"metrics.distinct_scopes",
 	"metrics.usage_series",
@@ -23,6 +33,8 @@ export const EXPECTED_OPERATION_NAMES = [
 	"benchmark.refresh",
 	"benchmark.status",
 	"benchmark.query",
+	"session.register",
+	"session.release",
 	"models.rank",
 	"context.assess",
 	"compaction.estimate",
@@ -39,8 +51,12 @@ export const EXPECTED_OPERATION_NAMES = [
 ] as const;
 
 export type OperationName = typeof EXPECTED_OPERATION_NAMES[number];
+interface RouterScopeInput { session_id?: string; session_secret?: string }
 export interface OperationInputs {
+	"session.register": { session_id: string };
+	"session.release": { session_id: string; session_secret?: string };
 	"metrics.record": MetricObservation;
+	"metrics.record_batch": { observations: MetricObservation[] };
 	"metrics.query": MetricQuery;
 	"metrics.distinct_scopes": { source: string; since: number; until: number; limit?: number };
 	"metrics.usage_series": { source: string; since: number; until: number; bucketSizeMs: number; bucketCount: number; scopeLimit?: number };
@@ -49,22 +65,25 @@ export interface OperationInputs {
 	"benchmark.refresh": { force?: boolean };
 	"benchmark.status": Record<string, never>;
 	"benchmark.query": BenchmarkQuery;
-	"models.rank": ModelRecommendationInput;
+	"models.rank": ModelRecommendationInput & RouterScopeInput;
 	"context.assess": { since?: number; until?: number };
 	"compaction.estimate": Record<string, never>;
 	"service.checkpoint": Record<string, never>;
 	"telemetry.poll": Record<string, never>;
-	"router.status": Record<string, never>;
-	"router.decide": Record<string, never>;
-	"router.pause": Record<string, never>;
-	"router.resume": Record<string, never>;
-	"router.override": RouteOverride;
-	"router.clear_override": Record<string, never>;
-	"router.current_route": Route;
-	"router.available_routes": { routes: Route[] };
+	"router.status": RouterScopeInput;
+	"router.decide": RouterScopeInput;
+	"router.pause": RouterScopeInput;
+	"router.resume": RouterScopeInput;
+	"router.override": RouteOverride & RouterScopeInput;
+	"router.clear_override": RouterScopeInput;
+	"router.current_route": Route & RouterScopeInput;
+	"router.available_routes": { routes: Route[] } & RouterScopeInput;
 }
 export interface OperationOutputs {
+	"session.register": RegisterSessionIdentityResult;
+	"session.release": { released: boolean };
 	"metrics.record": StoredMetricObservation;
+	"metrics.record_batch": StoredMetricObservation[];
 	"metrics.query": StoredMetricObservation[];
 	"metrics.distinct_scopes": string[];
 	"metrics.usage_series": { rows: UsageAggregateRow[]; truncated: boolean };
@@ -89,6 +108,7 @@ export interface OperationOutputs {
 }
 
 export class UnknownOperationError extends Error {}
+export { InvalidSessionSecretError };
 
 class UnavailableModelRanker implements ModelRanker {
 	rank(): ModelRankingResult { throw new Error("model ranking is not configured"); }
@@ -114,12 +134,30 @@ class UnavailableRouter implements RouterController {
 }
 
 export class JittorService {
+	private readonly router: RouterController;
+	private readonly operations: OperationHandlerMap;
+
 	constructor(
 		private readonly metrics: MetricStore,
-		private readonly router: RouterController = new UnavailableRouter(),
-		private readonly benchmarks: BenchmarkController = new UnavailableBenchmarkController(),
-		private readonly modelRanker: ModelRanker = new UnavailableModelRanker(),
-	) {}
+		router: RouterController = new UnavailableRouter(),
+		benchmarks: BenchmarkController = new UnavailableBenchmarkController(),
+		modelRanker: ModelRanker = new UnavailableModelRanker(),
+		sessionIdentity?: SessionIdentity,
+	) {
+		this.router = router;
+		const authorize = routerMutationAuthorizer(sessionIdentity);
+		// Each capability module owns a disjoint, bounded slice of EXPECTED_OPERATION_NAMES and only
+		// the collaborators it needs -- adding a new operation domain means adding a new module here,
+		// not another switch case in a single responsibility magnet.
+		this.operations = {
+			...metricsOperations(metrics),
+			...benchmarkOperations(benchmarks),
+			...contextOperations(metrics),
+			...routerOperations(router, authorize),
+			...modelRankingOperations(modelRanker, router, authorize),
+			...sessionIdentityOperations(sessionIdentity),
+		};
+	}
 
 	operationNames(): OperationName[] {
 		return [...EXPECTED_OPERATION_NAMES];
@@ -128,110 +166,13 @@ export class JittorService {
 	async execute<Name extends OperationName>(operation: Name, input: OperationInputs[Name]): Promise<OperationOutputs[Name]>;
 	async execute(operation: string, input: Record<string, unknown>): Promise<unknown>;
 	async execute(operation: string, input: Record<string, unknown> = {}): Promise<unknown> {
-		switch (operation) {
-			case "metrics.record": return this.metrics.record(validateMetricObservation(input));
-			case "metrics.query": return this.metrics.query(input as MetricQuery);
-			case "metrics.distinct_scopes": {
-				const source = input["source"];
-				const since = input["since"];
-				const until = input["until"];
-				if (typeof source !== "string" || source.length === 0) throw new Error("source is required");
-				if (!Number.isSafeInteger(since) || !Number.isSafeInteger(until) || (since as number) < 0 || (until as number) < (since as number)) {
-					throw new Error("distinct scopes requires non-negative ordered integer bounds");
-				}
-				const requestedLimit = input["limit"];
-				const limit = Number.isFinite(requestedLimit) ? Math.max(1, Math.min(USAGE_MAX_DISTINCT_SCOPES, Math.floor(requestedLimit as number))) : USAGE_MAX_DISTINCT_SCOPES;
-				return this.metrics.distinctScopes({ source, since: since as number, until: until as number, limit });
-			}
-			case "metrics.usage_series": {
-				const source = input["source"];
-				const since = input["since"];
-				const until = input["until"];
-				const bucketSizeMs = input["bucketSizeMs"];
-				const bucketCount = input["bucketCount"];
-				if (typeof source !== "string" || source.length === 0) throw new Error("source is required");
-				if (!Number.isSafeInteger(since) || !Number.isSafeInteger(until) || (since as number) < 0 || (until as number) < (since as number)) {
-					throw new Error("usage series requires non-negative ordered integer bounds");
-				}
-				if (typeof bucketSizeMs !== "number" || !Number.isFinite(bucketSizeMs) || bucketSizeMs <= 0) throw new Error("bucketSizeMs must be a positive number");
-				if (!Number.isInteger(bucketCount) || (bucketCount as number) <= 0 || (bucketCount as number) > MAX_USAGE_BUCKETS) {
-					throw new Error(`bucketCount must be a positive integer up to ${MAX_USAGE_BUCKETS}`);
-				}
-				const requestedScopeLimit = input["scopeLimit"];
-				const scopeLimit = Number.isFinite(requestedScopeLimit) ? Math.max(1, Math.min(USAGE_MAX_DISTINCT_SCOPES, Math.floor(requestedScopeLimit as number))) : USAGE_MAX_DISTINCT_SCOPES;
-				const scopes = this.metrics.distinctScopes({ source, since: since as number, until: until as number, limit: scopeLimit });
-				// More distinct scopes may exist beyond this bounded list -- that is the only remaining
-				// truncation risk once aggregation replaces a per-scope raw-row fetch (see aggregateUsage's
-				// own doc comment for the incident this was built to stop repeating).
-				const truncated = scopes.length >= scopeLimit;
-				const rows = scopes.length === 0 ? [] : this.metrics.aggregateUsage({
-					source, scopes, since: since as number, until: until as number, bucketSizeMs, bucketCount: bucketCount as number,
-				});
-				return { rows, truncated };
-			}
-			case "metrics.cost_by_task": {
-				const since = input["since"];
-				const until = input["until"];
-				if (!Number.isSafeInteger(since) || !Number.isSafeInteger(until) || (since as number) < 0 || (until as number) < (since as number)) {
-					throw new Error("cost by task requires non-negative ordered integer bounds");
-				}
-				const rows = this.metrics.query({ source: "pi", since: since as number, until: until as number, order: "desc", limit: TASK_COST_QUERY_LIMIT });
-				return buildTaskCostSummary(rows, { since: since as number, until: until as number, truncated: rows.length >= TASK_COST_QUERY_LIMIT });
-			}
-			case "metrics.prune": {
-				const before = input["before"];
-				if (typeof before !== "number") throw new Error("before is required");
-				const force = input["force"] === true;
-				const minCutoff = Date.now() - PRUNE_MIN_AGE_MS;
-				if (!force && before > minCutoff) {
-					throw new Error(`refusing to prune metrics newer than ${new Date(minCutoff).toISOString()} without force: true (this looked like it could delete recent or live data)`);
-				}
-				return { deleted: this.metrics.pruneBefore(before) };
-			}
-			case "benchmark.refresh": return this.benchmarks.refresh(input["force"] === true);
-			case "benchmark.status": return this.benchmarks.status();
-			case "benchmark.query": return this.benchmarks.query(input as unknown as BenchmarkQuery);
-			case "models.rank": {
-				const result = this.modelRanker.rank(input as unknown as ModelRecommendationInput);
-				if (result.automaticSelection && this.router.applyModelRanking) this.router.applyModelRanking(result.ranked.map((item) => item.candidate));
-				return result;
-			}
-			case "context.assess": {
-				const until = input["until"] === undefined ? Date.now() : input["until"];
-				const since = input["since"] === undefined && typeof until === "number" ? Math.max(0, until - CONTEXT_ASSESSMENT_DEFAULT_WINDOW_MS) : input["since"];
-				if (!Number.isSafeInteger(since) || !Number.isSafeInteger(until) || (since as number) < 0 || (until as number) < (since as number)) throw new Error("context assessment requires non-negative ordered integer bounds");
-				const query = { since: since as number, until: until as number, order: "asc" as const, limit: CONTEXT_ASSESSMENT_QUERY_LIMIT };
-				const injections = this.metrics.query({ ...query, source: "papyrus-context", metric: "injected-characters" });
-				const compactions = this.metrics.query({ ...query, source: "pi-context" });
-				return assessContextTelemetry(injections, compactions, {
-					since: since as number,
-					until: until as number,
-					truncated: injections.length >= CONTEXT_ASSESSMENT_QUERY_LIMIT || compactions.length >= CONTEXT_ASSESSMENT_QUERY_LIMIT,
-				});
-			}
-			case "compaction.estimate": {
-				const rows = this.metrics.query({
-					source: "pi-context", scope: "compaction", metric: "compaction-duration",
-					order: "desc", limit: COMPACTION_DURATION_ESTIMATE_MAX_SAMPLES,
-				});
-				return estimateCompactionDuration(rows);
-			}
-			case "service.checkpoint": this.metrics.checkpoint(); return { ok: true };
-			case "telemetry.poll": return this.router.poll();
-			case "router.status": return this.router.status();
-			case "router.decide": return this.router.decide();
-			case "router.pause": return this.router.pause();
-			case "router.resume": return this.router.resume();
-			case "router.override": return this.router.setOverride(input as unknown as RouteOverride);
-			case "router.clear_override": return this.router.clearOverride();
-			case "router.current_route": return this.router.setCurrentRoute(input as unknown as Route);
-			case "router.available_routes": return this.router.setAvailableRoutes(Array.isArray(input["routes"]) ? input["routes"] as Route[] : []);
-			default: throw new UnknownOperationError(`unknown operation: ${operation}`);
-		}
+		const handler = this.operations[operation];
+		if (!handler) throw new UnknownOperationError(`unknown operation: ${operation}`);
+		return handler(input);
 	}
 
 	ready(): boolean {
-		return this.router.status().ready;
+		return this.router.status(undefined).ready;
 	}
 
 	close(): void {
@@ -284,6 +225,7 @@ export function createApp(options: JittorAppOptions): { fetch(request: Request):
 				return json({ result: await options.service.execute(body.op, input) });
 			} catch (error) {
 				if (error instanceof UnknownOperationError) return json({ error: error.message }, 404);
+				if (error instanceof InvalidSessionSecretError) return json({ error: error.message }, 403);
 				return json({ error: error instanceof Error ? error.message : String(error) }, 400);
 			}
 		},

package/src/session-identity-service.ts

@@ -0,0 +1,55 @@
+import { isSessionRegistered, registerSessionIdentity, releaseSessionIdentity, verifySessionSecret } from "@danypops/daemon-kit/session-identity";
+import type { SessionIdentityStore } from "./ports/session-identity-store.ts";
+
+export interface RegisterSessionIdentityResult {
+	sessionId: string;
+	secret: string;
+}
+
+/** Thrown when a session_id has a registered identity but the caller did not present a matching session_secret. Mapped to HTTP 403 in service.ts, separate from generic validation's 400. */
+export class InvalidSessionSecretError extends Error {}
+
+function assertValidSessionId(sessionId: string): void {
+	if (typeof sessionId !== "string" || sessionId.length === 0) throw new Error("session_id is required");
+}
+
+/**
+ * Wraps daemon-kit's storage-agnostic session-identity primitive against Jittor's own
+ * SQLite-backed store, and enforces it at the one place a caller-supplied session_id is
+ * behavior-affecting: mutating router.* operations (see ports/router-controller.ts).
+ *
+ * Opt-in armor, not a breaking migration: a session_id that was never registered mutates
+ * exactly as before (undefined sessionId included, since that maps to the router's legacy
+ * "global" scope). Only once a sessionId is registered does a matching session_secret become
+ * mandatory. Every real Pi session becomes armored automatically once its extension fires
+ * session_start and registers.
+ */
+export class SessionIdentity {
+	constructor(private readonly store: SessionIdentityStore) {}
+
+	register(sessionId: string): RegisterSessionIdentityResult {
+		assertValidSessionId(sessionId);
+		return registerSessionIdentity(this.store, sessionId);
+	}
+
+	release(sessionId: string, secret: string | undefined): { released: boolean } {
+		assertValidSessionId(sessionId);
+		const wasRegistered = isSessionRegistered(this.store, sessionId);
+		releaseSessionIdentity(this.store, sessionId, secret);
+		return { released: wasRegistered && !isSessionRegistered(this.store, sessionId) };
+	}
+
+	isRegistered(sessionId: string): boolean {
+		return isSessionRegistered(this.store, sessionId);
+	}
+
+	verify(sessionId: string, secret: string | undefined): boolean {
+		return verifySessionSecret(this.store, sessionId, secret);
+	}
+
+	assertAuthorized(sessionId: string | undefined, secret: string | undefined): void {
+		if (sessionId === undefined) return;
+		if (!this.isRegistered(sessionId)) return;
+		if (!this.verify(sessionId, secret)) throw new InvalidSessionSecretError(`session "${sessionId}" is registered; a valid session_secret is required to mutate its router state`);
+	}
+}