@classytic/stage 0.3.0 → 0.4.0

package/dist/networking/cloud/inference.d.mts

@@ -0,0 +1,118 @@
+//#region src/networking/cloud/inference.d.ts
+type ModelSize = "8b" | "70b";
+type Precision = "fp16" | "int8";
+type GpuMemory = 24 | 80;
+type BatchSize = 1 | 8 | 32;
+type ContextSize = 2048 | 8192;
+type PromptTokens = 128 | 1024 | 4096;
+type OutputTokens = 32 | 256 | 1024;
+type InferenceScheduler = "shared" | "prefill-priority" | "decode-priority";
+type PrefixTokens = 0 | 512 | 2048 | 4096;
+type UniquePromptTokens = 128 | 512;
+type PrefixCacheState = "cold" | "warm";
+type PrefixCacheScope = "shared" | "tenant-isolated";
+type PrefixRequester = "same-tenant" | "other-tenant";
+type DistributedStrategy = "replicas" | "tensor-parallel";
+type GpuCount = 1 | 2 | 4 | 8;
+type GpuInterconnect = "local-fast" | "local-limited" | "cross-node";
+type ModelRoutingPolicy = "always-small" | "always-large" | "adaptive";
+type InferenceWorkloadMix = "mostly-simple" | "mixed" | "mostly-complex";
+type ResponseQualityTarget = "standard" | "strict";
+interface InferenceCapacityResult {
+  model: ModelSize;
+  precision: Precision;
+  gpuMemory: GpuMemory;
+  gpus: number;
+  batch: BatchSize;
+  context: ContextSize;
+  weightsGb: number;
+  kvCacheGb: number;
+  requiredGb: number;
+  availableGb: number;
+  fits: boolean;
+  topology: "replicas" | "tensor-parallel" | "cannot-load";
+  replicas: number;
+  tokensPerSecond: number;
+  ttftMs: number;
+  memoryHeadroomGb: number;
+  diagnosis: string;
+}
+interface InferenceRequestResult {
+  promptTokens: PromptTokens;
+  outputTokens: OutputTokens;
+  concurrentRequests: number;
+  scheduler: InferenceScheduler;
+  prefillWork: number;
+  decodeWork: number;
+  ttftMs: number;
+  interTokenMs: number;
+  completionMs: number;
+  activeKvTokens: number;
+  bottleneck: "prefill" | "decode" | "balanced";
+  diagnosis: string;
+}
+interface PrefixCacheResult {
+  prefixTokens: PrefixTokens;
+  uniqueTokens: UniquePromptTokens;
+  cacheState: PrefixCacheState;
+  scope: PrefixCacheScope;
+  requester: PrefixRequester;
+  reusableTokens: number;
+  computedTokens: number;
+  hitRatePercent: number;
+  prefillMs: number;
+  savedPrefillMs: number;
+  privacyRisk: boolean;
+  outcome: "cold-miss" | "cache-hit" | "isolated-miss" | "no-prefix";
+  diagnosis: string;
+}
+interface DistributedInferenceResult {
+  model: ModelSize;
+  strategy: DistributedStrategy;
+  gpus: GpuCount;
+  interconnect: GpuInterconnect;
+  modelGb: number;
+  memoryPerGpuGb: number;
+  fits: boolean;
+  servingCopies: number;
+  ranksPerRequest: number;
+  computeMsPerToken: number;
+  communicationMsPerToken: number;
+  tokenStepMs: number;
+  relativeThroughput: number;
+  failedGpuImpact: "one-replica" | "whole-shard-group" | "service-offline";
+  diagnosis: string;
+}
+interface ModelRoutingResult {
+  policy: ModelRoutingPolicy;
+  workload: InferenceWorkloadMix;
+  qualityTarget: ResponseQualityTarget;
+  requests: number;
+  simpleRequests: number;
+  complexRequests: number;
+  smallModelRequests: number;
+  largeModelRequests: number;
+  usefulResponses: number;
+  usefulRatePercent: number;
+  requiredUsefulRatePercent: number;
+  meetsQualityTarget: boolean;
+  totalCostUnits: number;
+  costPerRequest: number;
+  costPerUsefulResponse: number;
+  averageLatencyUnits: number;
+  diagnosis: string;
+}
+/** Comparative routing model; cost, latency and quality units are illustrative rather than vendor benchmarks. */
+declare function simulateModelRouting(policy: ModelRoutingPolicy, workload: InferenceWorkloadMix, qualityTarget: ResponseQualityTarget): ModelRoutingResult;
+/** Comparative distributed-serving model; values show topology effects, not vendor benchmarks. */
+declare function simulateDistributedInference(model: ModelSize, strategy: DistributedStrategy, gpus: GpuCount, interconnect: GpuInterconnect): DistributedInferenceResult;
+/** Models full-block KV prefix reuse. It never treats semantic similarity as cache identity. */
+declare function simulatePrefixCache(prefixTokens: PrefixTokens, uniqueTokens: UniquePromptTokens, cacheState: PrefixCacheState, scope: PrefixCacheScope, requester: PrefixRequester): PrefixCacheResult;
+/**
+ * Comparative teaching model for the two phases of autoregressive inference.
+ * Values are dimensioned and monotonic, but are not claims about a particular model or GPU.
+ */
+declare function simulateInferenceRequest(promptTokens: PromptTokens, outputTokens: OutputTokens, concurrentRequests: number, scheduler: InferenceScheduler): InferenceRequestResult;
+declare function planInference(model: ModelSize, precision: Precision, gpuMemory: GpuMemory, gpus: number, batch: BatchSize, context: ContextSize): InferenceCapacityResult;
+//#endregion
+export { BatchSize, ContextSize, DistributedInferenceResult, DistributedStrategy, GpuCount, GpuInterconnect, GpuMemory, InferenceCapacityResult, InferenceRequestResult, InferenceScheduler, InferenceWorkloadMix, ModelRoutingPolicy, ModelRoutingResult, ModelSize, OutputTokens, Precision, PrefixCacheResult, PrefixCacheScope, PrefixCacheState, PrefixRequester, PrefixTokens, PromptTokens, ResponseQualityTarget, UniquePromptTokens, planInference, simulateDistributedInference, simulateInferenceRequest, simulateModelRouting, simulatePrefixCache };

package/dist/networking/cloud/inference.mjs

@@ -0,0 +1,179 @@
+//#region src/networking/cloud/inference.ts
+/** Comparative routing model; cost, latency and quality units are illustrative rather than vendor benchmarks. */
+function simulateModelRouting(policy, workload, qualityTarget) {
+	const requests = 100;
+	const simpleRequests = workload === "mostly-simple" ? 85 : workload === "mixed" ? 60 : 25;
+	const complexRequests = requests - simpleRequests;
+	const smallModelRequests = policy === "always-small" ? requests : policy === "always-large" ? 0 : Math.round(simpleRequests * .85 + complexRequests * .1);
+	const largeModelRequests = requests - smallModelRequests;
+	const useful = (count, rate) => count * rate;
+	let usefulResponses;
+	if (policy === "always-small") usefulResponses = useful(simpleRequests, .94) + useful(complexRequests, .54);
+	else if (policy === "always-large") usefulResponses = useful(simpleRequests, .98) + useful(complexRequests, .9);
+	else {
+		const simpleToSmall = Math.round(simpleRequests * .85);
+		const complexToSmall = Math.round(complexRequests * .1);
+		usefulResponses = useful(simpleToSmall, .94) + useful(simpleRequests - simpleToSmall, .98) + useful(complexToSmall, .54) + useful(complexRequests - complexToSmall, .9);
+	}
+	const roundedUseful = Math.round(usefulResponses * 10) / 10;
+	const totalCostUnits = smallModelRequests + largeModelRequests * 6;
+	const routerLatency = policy === "adaptive" ? .1 : 0;
+	const averageLatencyUnits = (smallModelRequests * .8 + largeModelRequests * 2.4) / requests + routerLatency;
+	const requiredUsefulRatePercent = qualityTarget === "strict" ? 92 : 80;
+	const meetsQualityTarget = roundedUseful >= requiredUsefulRatePercent;
+	const costPerUsefulResponse = Math.round(totalCostUnits / Math.max(1, roundedUseful) * 100) / 100;
+	const diagnosis = !meetsQualityTarget ? "Cheap requests are not cheap outcomes when too many responses fail the workload quality gate." : policy === "always-large" ? "Quality clears the gate, but simple requests consume the same expensive capacity as complex ones." : policy === "adaptive" ? "The router spends large-model capacity selectively; evaluate its decisions on a representative workload, not prompt anecdotes." : "The small model clears this workload's quality gate, so added routing complexity would not yet earn its cost.";
+	return {
+		policy,
+		workload,
+		qualityTarget,
+		requests,
+		simpleRequests,
+		complexRequests,
+		smallModelRequests,
+		largeModelRequests,
+		usefulResponses: roundedUseful,
+		usefulRatePercent: roundedUseful,
+		requiredUsefulRatePercent,
+		meetsQualityTarget,
+		totalCostUnits,
+		costPerRequest: Math.round(totalCostUnits / requests * 100) / 100,
+		costPerUsefulResponse,
+		averageLatencyUnits: Math.round(averageLatencyUnits * 100) / 100,
+		diagnosis
+	};
+}
+/** Comparative distributed-serving model; values show topology effects, not vendor benchmarks. */
+function simulateDistributedInference(model, strategy, gpus, interconnect) {
+	const modelGb = model === "8b" ? 17.3 : 151.2;
+	const memoryPerGpuGb = strategy === "tensor-parallel" ? modelGb / gpus : modelGb;
+	const fits = memoryPerGpuGb + 4 <= 80;
+	const servingCopies = fits ? strategy === "replicas" ? gpus : 1 : 0;
+	const ranksPerRequest = strategy === "tensor-parallel" ? gpus : 1;
+	const baseComputeMs = model === "8b" ? 12 : 34;
+	const computeMsPerToken = strategy === "tensor-parallel" ? Math.round(baseComputeMs / Math.pow(gpus, .72) * 10) / 10 : baseComputeMs;
+	const communicationMsPerToken = strategy === "tensor-parallel" && gpus > 1 ? Math.round((interconnect === "local-fast" ? .7 : interconnect === "local-limited" ? 2.2 : 6.5) * Math.log2(gpus) * 10) / 10 : 0;
+	const tokenStepMs = fits ? Math.round((computeMsPerToken + communicationMsPerToken) * 10) / 10 : 0;
+	const relativeThroughput = fits ? Math.round((strategy === "replicas" ? gpus : baseComputeMs / Math.max(1, tokenStepMs)) * 100) / 100 : 0;
+	const failedGpuImpact = gpus === 1 ? "service-offline" : strategy === "replicas" ? "one-replica" : "whole-shard-group";
+	const diagnosis = !fits ? strategy === "replicas" ? "A complete model copy must fit on every replica. Adding more GPUs does not combine their memory." : "The shard plus runtime workspace still exceeds memory per GPU. Add ranks or reduce model memory." : strategy === "replicas" ? `${gpus} independent copies serve different requests without a collective on every token step.` : communicationMsPerToken >= computeMsPerToken ? "Collective communication costs at least as much as shard compute, so more ranks no longer mean proportional speedup." : "Each token uses every rank: compute is divided, then intermediate results are exchanged before generation continues.";
+	return {
+		model,
+		strategy,
+		gpus,
+		interconnect,
+		modelGb,
+		memoryPerGpuGb: Math.round(memoryPerGpuGb * 10) / 10,
+		fits,
+		servingCopies,
+		ranksPerRequest,
+		computeMsPerToken,
+		communicationMsPerToken,
+		tokenStepMs,
+		relativeThroughput,
+		failedGpuImpact,
+		diagnosis
+	};
+}
+/** Models full-block KV prefix reuse. It never treats semantic similarity as cache identity. */
+function simulatePrefixCache(prefixTokens, uniqueTokens, cacheState, scope, requester) {
+	const fullBlockTokens = Math.floor(prefixTokens / 16) * 16;
+	const isolated = scope === "tenant-isolated" && requester === "other-tenant";
+	const reusableTokens = cacheState === "warm" && !isolated ? fullBlockTokens : 0;
+	const totalPromptTokens = prefixTokens + uniqueTokens;
+	const computedTokens = totalPromptTokens - reusableTokens;
+	const baselinePrefillMs = 60 + totalPromptTokens * .21;
+	const prefillMs = Math.round(60 + computedTokens * .21);
+	const savedPrefillMs = Math.round(baselinePrefillMs - prefillMs);
+	const hitRatePercent = totalPromptTokens === 0 ? 0 : Math.round(reusableTokens / totalPromptTokens * 100);
+	const privacyRisk = scope === "shared" && requester === "other-tenant" && reusableTokens > 0;
+	const outcome = prefixTokens === 0 ? "no-prefix" : isolated ? "isolated-miss" : reusableTokens > 0 ? "cache-hit" : "cold-miss";
+	return {
+		prefixTokens,
+		uniqueTokens,
+		cacheState,
+		scope,
+		requester,
+		reusableTokens,
+		computedTokens,
+		hitRatePercent,
+		prefillMs,
+		savedPrefillMs,
+		privacyRisk,
+		outcome,
+		diagnosis: outcome === "cache-hit" ? privacyRisk ? "Prefill work is reused across tenants, but the latency difference can reveal that another tenant used this exact prefix." : "The identical full prefix blocks skip repeated prefill; the unique suffix still has to be computed." : outcome === "isolated-miss" ? "Tenant isolation prevents cross-tenant reuse, trading some compute for a safer cache boundary." : outcome === "cold-miss" ? "The prefix is not resident yet, so this request computes it and can warm the cache for later requests." : "There is no shared prefix to reuse; every prompt token must be computed."
+	};
+}
+/**
+* Comparative teaching model for the two phases of autoregressive inference.
+* Values are dimensioned and monotonic, but are not claims about a particular model or GPU.
+*/
+function simulateInferenceRequest(promptTokens, outputTokens, concurrentRequests, scheduler) {
+	const requests = Math.max(1, Math.min(32, Math.round(concurrentRequests)));
+	const queueFactor = 1 + (requests - 1) * .055;
+	const prefillBias = scheduler === "prefill-priority" ? .72 : scheduler === "decode-priority" ? 1.35 : 1;
+	const decodeBias = scheduler === "decode-priority" ? .76 : scheduler === "prefill-priority" ? 1.28 : 1;
+	const ttftMs = Math.round((70 + promptTokens * .21) * queueFactor * prefillBias);
+	const interTokenMs = Math.round((18 + requests * 1.45) * decodeBias);
+	const completionMs = ttftMs + interTokenMs * outputTokens;
+	const prefillWork = promptTokens * requests;
+	const decodeWork = outputTokens * requests;
+	const activeKvTokens = (promptTokens + Math.ceil(outputTokens / 2)) * requests;
+	const ratio = prefillWork / Math.max(1, decodeWork);
+	const bottleneck = ratio > 2 ? "prefill" : ratio < .5 ? "decode" : "balanced";
+	return {
+		promptTokens,
+		outputTokens,
+		concurrentRequests: requests,
+		scheduler,
+		prefillWork,
+		decodeWork,
+		ttftMs,
+		interTokenMs,
+		completionMs,
+		activeKvTokens,
+		bottleneck,
+		diagnosis: bottleneck === "prefill" ? "Prompt processing dominates. Time to first token and admission pressure matter most." : bottleneck === "decode" ? "Token generation dominates. Inter-token latency and growing KV state matter most." : "Prompt processing and token generation both materially affect the request."
+	};
+}
+function planInference(model, precision, gpuMemory, gpus, batch, context) {
+	const count = Math.max(1, Math.min(4, Math.round(gpus)));
+	const weightsGb = (model === "8b" ? 8 : 70) * (precision === "fp16" ? 2 : 1) * 1.08;
+	const kvPerToken = model === "8b" ? 12e-5 : 32e-5;
+	const kvCacheGb = batch * context * kvPerToken;
+	const perReplicaNeed = weightsGb + kvCacheGb + 4;
+	const topology = perReplicaNeed <= gpuMemory ? "replicas" : perReplicaNeed <= gpuMemory * count ? "tensor-parallel" : "cannot-load";
+	const replicas = topology === "replicas" ? count : topology === "tensor-parallel" ? 1 : 0;
+	const availableGb = gpuMemory * count;
+	const requiredGb = topology === "replicas" ? perReplicaNeed * count : perReplicaNeed;
+	const fits = topology !== "cannot-load";
+	const base = model === "8b" ? 90 : 28;
+	const batchGain = 1 + Math.log2(batch) * .55;
+	const parallelGain = topology === "tensor-parallel" ? Math.pow(count, .72) : count;
+	const tokensPerSecond = fits ? Math.round(base * batchGain * parallelGain) : 0;
+	const ttftMs = fits ? Math.round((model === "8b" ? 180 : 520) + (batch - 1) * 18 + (context / 2048 - 1) * 90 + (topology === "tensor-parallel" ? (count - 1) * 45 : 0)) : 0;
+	const memoryHeadroomGb = Math.round((availableGb - requiredGb) * 10) / 10;
+	const diagnosis = !fits ? "Model weights, KV cache and runtime workspace exceed aggregate GPU memory. Quantize, shorten context, reduce batch or add memory." : topology === "tensor-parallel" ? `The model is sharded across ${count} GPUs. It fits, but every token requires cross-GPU coordination.` : batch === 32 ? "Large continuous batches raise total throughput while increasing queueing and time to first token." : `Each GPU holds a complete model copy, so ${replicas} independent replicas can serve requests in parallel.`;
+	return {
+		model,
+		precision,
+		gpuMemory,
+		gpus: count,
+		batch,
+		context,
+		weightsGb: Math.round(weightsGb * 10) / 10,
+		kvCacheGb: Math.round(kvCacheGb * 10) / 10,
+		requiredGb: Math.round(requiredGb * 10) / 10,
+		availableGb,
+		fits,
+		topology,
+		replicas,
+		tokensPerSecond,
+		ttftMs,
+		memoryHeadroomGb,
+		diagnosis
+	};
+}
+
+//#endregion
+export { planInference, simulateDistributedInference, simulateInferenceRequest, simulateModelRouting, simulatePrefixCache };

package/dist/networking/cloud/infrastructure.d.mts

@@ -0,0 +1,45 @@
+//#region src/networking/cloud/infrastructure.d.ts
+type InfrastructureIntent = "keep" | "scale-four" | "larger-nodes";
+type ExternalChange = "none" | "manual-scale" | "open-admin";
+type DriftResolution = "enforce-config" | "adopt-actual";
+type InfrastructurePhase = "baseline" | "refresh" | "plan" | "apply";
+interface InfrastructureShape {
+  replicas: number;
+  nodeSize: "small" | "large";
+  adminAccess: "private" | "public";
+}
+interface InfrastructurePlan {
+  intent: InfrastructureIntent;
+  externalChange: ExternalChange;
+  resolution: DriftResolution;
+}
+interface InfrastructureSnapshot {
+  plan: InfrastructurePlan;
+  step: number;
+  phase: InfrastructurePhase;
+  configuration: InfrastructureShape;
+  recordedState: InfrastructureShape;
+  actual: InfrastructureShape;
+  target: InfrastructureShape;
+  driftCount: number;
+  remainingDifferences: number;
+  plannedChanges: number;
+  infrastructureChanged: boolean;
+  codeUpdated: boolean;
+  converged: boolean;
+  unsafeExposure: boolean;
+  message: string;
+}
+type InfrastructureCommand = {
+  type: "advance";
+} | {
+  type: "reset";
+};
+declare function infrastructureSnapshot(plan: InfrastructurePlan, step?: number): InfrastructureSnapshot;
+declare function transitionInfrastructure(current: InfrastructureSnapshot, command: InfrastructureCommand): InfrastructureSnapshot;
+declare function createInfrastructureEngine(plan: InfrastructurePlan): {
+  readonly state: InfrastructureSnapshot;
+  dispatch(command: InfrastructureCommand): InfrastructureSnapshot;
+};
+//#endregion
+export { DriftResolution, ExternalChange, InfrastructureCommand, InfrastructureIntent, InfrastructurePhase, InfrastructurePlan, InfrastructureShape, InfrastructureSnapshot, createInfrastructureEngine, infrastructureSnapshot, transitionInfrastructure };

package/dist/networking/cloud/infrastructure.mjs

@@ -0,0 +1,96 @@
+//#region src/networking/cloud/infrastructure.ts
+const BASE = {
+	replicas: 2,
+	nodeSize: "small",
+	adminAccess: "private"
+};
+const PHASES = [
+	"baseline",
+	"refresh",
+	"plan",
+	"apply"
+];
+function configured(intent) {
+	if (intent === "scale-four") return {
+		...BASE,
+		replicas: 4
+	};
+	if (intent === "larger-nodes") return {
+		...BASE,
+		nodeSize: "large"
+	};
+	return { ...BASE };
+}
+function changedOutside(change) {
+	if (change === "manual-scale") return {
+		...BASE,
+		replicas: 3
+	};
+	if (change === "open-admin") return {
+		...BASE,
+		adminAccess: "public"
+	};
+	return { ...BASE };
+}
+function difference(left, right) {
+	return Number(left.replicas !== right.replicas) + Number(left.nodeSize !== right.nodeSize) + Number(left.adminAccess !== right.adminAccess);
+}
+function describe(snapshot) {
+	if (snapshot.phase === "baseline" && snapshot.driftCount > 0) return "Actual infrastructure changed outside the workflow. Recorded state still describes the last apply.";
+	if (snapshot.phase === "baseline") return snapshot.remainingDifferences > 0 ? "Configuration declares a new target. State and actual infrastructure still describe the last apply." : "Configuration, recorded state and actual infrastructure begin from a known baseline.";
+	if (snapshot.phase === "refresh") return snapshot.driftCount > 0 ? `Refresh observed ${snapshot.driftCount} difference. No remote object changed.` : "Refresh observed the remote objects. No external drift was found and nothing changed.";
+	if (snapshot.phase === "plan") return snapshot.plan.resolution === "adopt-actual" && snapshot.codeUpdated ? `Configuration now declares the observed reality. Review the ${snapshot.plannedChanges}-change plan before apply.` : `The plan proposes ${snapshot.plannedChanges} change${snapshot.plannedChanges === 1 ? "" : "s"} to make reality match configuration.`;
+	return snapshot.converged ? "Apply completed. Configuration, state and actual infrastructure now agree." : "Apply stopped before convergence; inspect the partial result before planning again.";
+}
+function infrastructureSnapshot(plan, step = 0) {
+	const currentStep = Math.max(0, Math.min(PHASES.length - 1, Math.round(step)));
+	const phase = PHASES[currentStep];
+	const desired = configured(plan.intent);
+	const outside = changedOutside(plan.externalChange);
+	const planned = currentStep >= 2;
+	const applied = currentStep >= 3;
+	const adopting = plan.resolution === "adopt-actual" && planned && plan.externalChange !== "none";
+	const configuration = adopting ? outside : desired;
+	const target = adopting ? outside : desired;
+	const actual = applied ? target : outside;
+	const recordedState = applied ? target : BASE;
+	const snapshot = {
+		plan,
+		step: currentStep,
+		phase,
+		configuration,
+		recordedState,
+		actual,
+		target,
+		driftCount: difference(BASE, outside),
+		remainingDifferences: difference(configuration, actual),
+		plannedChanges: planned ? difference(outside, target) : 0,
+		infrastructureChanged: applied && difference(outside, target) > 0,
+		codeUpdated: adopting,
+		converged: applied && difference(configuration, actual) === 0 && difference(recordedState, actual) === 0,
+		unsafeExposure: actual.adminAccess === "public"
+	};
+	return {
+		...snapshot,
+		message: describe(snapshot)
+	};
+}
+function transitionInfrastructure(current, command) {
+	if (command.type === "reset") return infrastructureSnapshot(current.plan);
+	return infrastructureSnapshot(current.plan, current.step + 1);
+}
+function createInfrastructureEngine(plan) {
+	let current = infrastructureSnapshot(plan);
+	return {
+		get state() {
+			return current;
+		},
+		dispatch(command) {
+			current = transitionInfrastructure(current, command);
+			return current;
+		}
+	};
+}
+
+//#endregion
+export { createInfrastructureEngine, infrastructureSnapshot, transitionInfrastructure };

package/dist/networking/cloud/observability.d.mts

@@ -0,0 +1,24 @@
+//#region src/networking/cloud/observability.d.ts
+type SloTarget = "99" | "99.9";
+type DependencyState = "healthy" | "slow" | "failing";
+type Telemetry = "metrics-only" | "correlated";
+interface SloIncidentResult {
+  requestsPerMinute: number;
+  sloTarget: SloTarget;
+  dependency: DependencyState;
+  telemetry: Telemetry;
+  errorRatePercent: number;
+  p95LatencyMs: number;
+  goodRatePercent: number;
+  burnRate: number;
+  budgetRequests: number;
+  badRequestsPerMinute: number;
+  minutesToExhaust: number;
+  action: "observe" | "ticket" | "page";
+  suspect: string;
+  evidence: string;
+  diagnosis: string;
+}
+declare function observeService(requestsPerMinute: number, sloTarget: SloTarget, dependency: DependencyState, telemetry: Telemetry): SloIncidentResult;
+//#endregion
+export { DependencyState, SloIncidentResult, SloTarget, Telemetry, observeService };

package/dist/networking/cloud/observability.mjs

@@ -0,0 +1,34 @@
+//#region src/networking/cloud/observability.ts
+function observeService(requestsPerMinute, sloTarget, dependency, telemetry) {
+	const rpm = Math.max(10, Math.min(1e4, Math.round(requestsPerMinute)));
+	const errorRatePercent = dependency === "healthy" ? .03 : dependency === "slow" ? .35 : 4.8;
+	const p95LatencyMs = dependency === "healthy" ? 180 : dependency === "slow" ? 1450 : 2800;
+	const allowedPercent = 100 - Number(sloTarget);
+	const goodRatePercent = Math.round((100 - errorRatePercent) * 100) / 100;
+	const burnRate = Math.round(errorRatePercent / allowedPercent * 10) / 10;
+	const budgetRequests = Math.round(rpm * 60 * 24 * 30 * allowedPercent / 100);
+	const badRequestsPerMinute = Math.round(rpm * errorRatePercent / 100);
+	const minutesToExhaust = Math.max(1, Math.round(1440 * 30 / burnRate));
+	const action = burnRate >= 14.4 ? "page" : burnRate >= 2 ? "ticket" : "observe";
+	const suspect = dependency === "healthy" ? "no dominant failing dependency" : dependency === "slow" ? "catalog database latency" : "payment dependency failures";
+	return {
+		requestsPerMinute: rpm,
+		sloTarget,
+		dependency,
+		telemetry,
+		errorRatePercent,
+		p95LatencyMs,
+		goodRatePercent,
+		burnRate,
+		budgetRequests,
+		badRequestsPerMinute,
+		minutesToExhaust,
+		action,
+		suspect,
+		evidence: telemetry === "correlated" ? `Trace spans isolate ${suspect}; linked logs carry the same trace ID.` : "Metrics expose customer symptoms, but no correlated trace identifies the responsible hop.",
+		diagnosis: action === "page" ? `Customer-visible failures burn the ${sloTarget}% objective ${burnRate}× faster than allowed. Page an operator and stop risky change.` : action === "ticket" ? `The service is consuming budget faster than planned, but the modeled exhaustion window permits scheduled investigation.` : "The service remains within its planned reliability consumption. Observe trends without paging a human."
+	};
+}
+
+//#endregion
+export { observeService };

package/dist/networking/cloud/orchestration.d.mts

@@ -0,0 +1,32 @@
+//#region src/networking/cloud/orchestration.d.ts
+/**
+ * Reconciliation: a declared desired state, the actual state, and a controller closing the gap.
+ *
+ * The misconception this exists to break is that a deployment is an INSTRUCTION. It is not. It is a
+ * declaration the cluster keeps trying to satisfy, which is why a failed Pod comes back on its own
+ * and why asking for more replicas than there are slots leaves Pods pending forever rather than
+ * failing loudly. Both of those follow from the same loop.
+ */
+type ClusterCapacity = "tight" | "ample";
+type ClusterFailure = "none" | "pod" | "node";
+type ReleaseState = "stable" | "rolling";
+interface OrchestrationResult {
+  desired: number;
+  capacity: ClusterCapacity;
+  failure: ClusterFailure;
+  release: ReleaseState;
+  slots: number;
+  /** Slots still schedulable after a failure removed some. */
+  usableSlots: number;
+  scheduled: number;
+  ready: number;
+  pending: number;
+  oldVersion: number;
+  newVersion: number;
+  replacementCreated: boolean;
+  available: boolean;
+  diagnosis: string;
+}
+declare function reconcileWorkload(desired: number, capacity: ClusterCapacity, failure: ClusterFailure, release: ReleaseState): OrchestrationResult;
+//#endregion
+export { ClusterCapacity, ClusterFailure, OrchestrationResult, ReleaseState, reconcileWorkload };

package/dist/networking/cloud/orchestration.mjs

@@ -0,0 +1,38 @@
+//#region src/networking/cloud/orchestration.ts
+function reconcileWorkload(desired, capacity, failure, release) {
+	const target = Math.max(1, Math.min(6, Math.round(desired)));
+	const slots = capacity === "ample" ? 6 : 3;
+	const usableSlots = Math.max(0, slots - (failure === "node" ? 2 : 0));
+	const scheduled = Math.min(target, usableSlots);
+	const pending = Math.max(0, target - scheduled);
+	/**
+	* Every scheduled Pod is ready, because the controller has already replaced whatever failed.
+	*
+	* That is the point of the loop rather than an oversight, and it is now written as one line. It
+	* used to read `scheduled - (failure === 'pod' && scheduled === target ? 0 : 0)`, which subtracts
+	* zero from zero either way: a conditional with the same value in both branches, dressed up to
+	* look like the failure was being accounted for somewhere.
+	*/
+	const ready = scheduled;
+	const replacementCreated = failure !== "none" && scheduled > 0;
+	const newVersion = release === "rolling" ? Math.min(ready, Math.max(1, Math.ceil(target / 2))) : 0;
+	return {
+		desired: target,
+		capacity,
+		failure,
+		release,
+		slots,
+		usableSlots,
+		scheduled,
+		ready,
+		pending,
+		oldVersion: ready - newVersion,
+		newVersion,
+		replacementCreated,
+		available: ready >= Math.max(1, target - 1),
+		diagnosis: pending ? `The controller still wants ${target} replicas, but only ${usableSlots} schedulable slots remain. ${pending} Pod${pending === 1 ? " is" : "s are"} pending.` : failure !== "none" ? `Actual state fell below the declaration, so the controller created replacement Pods until ${ready}/${target} were ready again.` : release === "rolling" ? `New Pods become ready before more old Pods are removed. ${newVersion} now run the new digest while availability is preserved.` : `Actual state matches the declared ${target} ready replicas.`
+	};
+}
+
+//#endregion
+export { reconcileWorkload };

package/dist/networking/cloud/recovery.d.mts

@@ -0,0 +1,21 @@
+//#region src/networking/cloud/recovery.d.ts
+type RecoveryStrategy = "backup" | "async-replica" | "sync-replica";
+type Incident = "primary-failure" | "bad-write";
+type WriteLoad = "normal" | "heavy";
+interface RecoveryResult {
+  strategy: RecoveryStrategy;
+  incident: Incident;
+  load: WriteLoad;
+  commitLatencyMs: number;
+  replicationLagSeconds: number;
+  rpoSeconds: number;
+  rtoMinutes: number;
+  automaticFailover: boolean;
+  pointInTimeRecovery: boolean;
+  meetsTarget: boolean;
+  recoveryAction: string;
+  diagnosis: string;
+}
+declare function evaluateRecovery(strategy: RecoveryStrategy, incident: Incident, load: WriteLoad): RecoveryResult;
+//#endregion
+export { Incident, RecoveryResult, RecoveryStrategy, WriteLoad, evaluateRecovery };

package/dist/networking/cloud/recovery.mjs

@@ -0,0 +1,27 @@
+//#region src/networking/cloud/recovery.ts
+function evaluateRecovery(strategy, incident, load) {
+	const heavy = load === "heavy";
+	const commitLatencyMs = strategy === "sync-replica" ? heavy ? 92 : 48 : heavy ? 24 : 18;
+	const replicationLagSeconds = strategy === "async-replica" ? heavy ? 45 : 4 : strategy === "sync-replica" ? 0 : 3600;
+	const pointInTimeRecovery = strategy === "backup";
+	const automaticFailover = incident === "primary-failure" && strategy !== "backup";
+	const rpoSeconds = incident === "bad-write" ? pointInTimeRecovery ? 300 : Number.POSITIVE_INFINITY : strategy === "backup" ? 3600 : replicationLagSeconds;
+	const rtoMinutes = incident === "bad-write" ? pointInTimeRecovery ? 45 : Number.POSITIVE_INFINITY : strategy === "backup" ? 180 : strategy === "async-replica" ? 8 : 5;
+	return {
+		strategy,
+		incident,
+		load,
+		commitLatencyMs,
+		replicationLagSeconds,
+		rpoSeconds,
+		rtoMinutes,
+		automaticFailover,
+		pointInTimeRecovery,
+		meetsTarget: rpoSeconds <= 300 && rtoMinutes <= 30,
+		recoveryAction: incident === "bad-write" ? pointInTimeRecovery ? "restore the last clean recovery point" : "find a clean backup; the replica copied the write" : strategy === "backup" ? "provision a database and restore the backup" : "fence the old primary, promote the standby, and redirect clients",
+		diagnosis: incident === "bad-write" && !pointInTimeRecovery ? "Replication preserved availability, not history: the unwanted write reached the replica too." : incident === "bad-write" ? "A point-in-time backup can recover state before the unwanted write, but restoration takes time." : strategy === "backup" ? "Backup and restore is inexpensive, but its older recovery point and rebuild time miss this target." : strategy === "async-replica" ? `Failover is fast, but ${replicationLagSeconds} seconds of unreplicated commits can be lost.` : "A synchronous standby reaches zero modeled RPO by making each commit wait for remote acknowledgement."
+	};
+}
+
+//#endregion
+export { evaluateRecovery };

package/dist/networking/cloud/releases.d.mts

@@ -0,0 +1,42 @@
+//#region src/networking/cloud/releases.d.ts
+type ReleaseStrategy = "recreate" | "rolling" | "canary" | "blue-green";
+type CandidateHealth = "healthy" | "faulty";
+type DataCompatibility = "compatible" | "breaking";
+type ReleaseStatus = "running" | "completed" | "rolled-back";
+interface ReleasePlan {
+  strategy: ReleaseStrategy;
+  replicas: number;
+  candidateHealth: CandidateHealth;
+  dataCompatibility: DataCompatibility;
+}
+interface ReleaseSnapshot {
+  plan: ReleasePlan;
+  step: number;
+  totalSteps: number;
+  oldReplicas: number;
+  newReplicas: number;
+  newTrafficPercent: number;
+  availableReplicas: number;
+  observedErrorPercent: number;
+  readinessSeconds: number;
+  rollbackSeconds: number;
+  dataSafe: boolean;
+  status: ReleaseStatus;
+  safeToContinue: boolean;
+  message: string;
+}
+type ReleaseCommand = {
+  type: "advance";
+} | {
+  type: "rollback";
+} | {
+  type: "reset";
+};
+declare function releaseSnapshot(plan: ReleasePlan, step?: number, status?: ReleaseStatus): ReleaseSnapshot;
+declare function transitionRelease(current: ReleaseSnapshot, command: ReleaseCommand): ReleaseSnapshot;
+declare function createReleaseEngine(plan: ReleasePlan): {
+  readonly state: ReleaseSnapshot;
+  dispatch(command: ReleaseCommand): ReleaseSnapshot;
+};
+//#endregion
+export { CandidateHealth, DataCompatibility, ReleaseCommand, ReleasePlan, ReleaseSnapshot, ReleaseStatus, ReleaseStrategy, createReleaseEngine, releaseSnapshot, transitionRelease };