@classytic/stage 0.2.0 → 0.4.0

package/dist/networking/cloud/releases.mjs

@@ -0,0 +1,135 @@
+//#region src/networking/cloud/releases.ts
+const TOTAL_STEPS = 4;
+const clampReplicas = (value) => Math.max(2, Math.min(6, Math.round(value)));
+function deploymentAt(plan, step) {
+	const replicas = clampReplicas(plan.replicas);
+	if (plan.strategy === "recreate") {
+		const stopped = step >= 1;
+		const started = step >= 3;
+		return {
+			step,
+			totalSteps: TOTAL_STEPS,
+			oldReplicas: stopped ? 0 : replicas,
+			newReplicas: started ? replicas : 0,
+			newTrafficPercent: started ? 100 : 0,
+			availableReplicas: stopped && !started ? 0 : replicas
+		};
+	}
+	if (plan.strategy === "rolling") {
+		const newReplicas = Math.min(replicas, Math.ceil(step / TOTAL_STEPS * replicas));
+		return {
+			step,
+			totalSteps: TOTAL_STEPS,
+			oldReplicas: replicas - newReplicas,
+			newReplicas,
+			newTrafficPercent: Math.round(newReplicas / replicas * 100),
+			availableReplicas: replicas
+		};
+	}
+	if (plan.strategy === "canary") {
+		const traffic = [
+			0,
+			5,
+			15,
+			30,
+			100
+		][step] ?? 100;
+		const complete = step === TOTAL_STEPS;
+		return {
+			step,
+			totalSteps: TOTAL_STEPS,
+			oldReplicas: complete ? 0 : replicas,
+			newReplicas: complete ? replicas : step === 0 ? 0 : 1,
+			newTrafficPercent: traffic,
+			availableReplicas: replicas
+		};
+	}
+	const switched = step === TOTAL_STEPS;
+	return {
+		step,
+		totalSteps: TOTAL_STEPS,
+		oldReplicas: switched ? 0 : replicas,
+		newReplicas: step === 0 ? 0 : replicas,
+		newTrafficPercent: switched ? 100 : 0,
+		availableReplicas: replicas
+	};
+}
+function describe(snapshot) {
+	if (snapshot.status === "rolled-back") return snapshot.dataSafe ? "Traffic is back on the stable version; the candidate is isolated." : "Traffic returned, but the shared data contract is incompatible and still blocks a safe rollback.";
+	if (snapshot.step === 0) return "The stable version serves all traffic. Start the release when ready.";
+	if (!snapshot.dataSafe) return "The candidate changes shared data incompatibly. Routing back would not restore the old contract.";
+	if (!snapshot.safeToContinue) return `${snapshot.newTrafficPercent}% of requests reach a faulty candidate. Roll back before increasing exposure.`;
+	if (snapshot.plan.strategy === "recreate" && snapshot.availableReplicas === 0) return "The old fleet is stopped before the candidate becomes ready, so the service is unavailable.";
+	if (snapshot.status === "completed") return "The candidate serves all traffic without crossing the error budget.";
+	if (snapshot.plan.strategy === "blue-green" && snapshot.newTrafficPercent === 0) return "The complete green fleet is ready, but users still reach blue until the traffic switch.";
+	return `${snapshot.newTrafficPercent}% of requests reach the candidate while the stable version remains available.`;
+}
+function releaseSnapshot(plan, step = 0, status = "running") {
+	const normalizedPlan = {
+		...plan,
+		replicas: clampReplicas(plan.replicas)
+	};
+	const dataSafe = normalizedPlan.dataCompatibility === "compatible";
+	if (status === "rolled-back") {
+		const rolledBack = {
+			plan: normalizedPlan,
+			step,
+			totalSteps: TOTAL_STEPS,
+			oldReplicas: normalizedPlan.replicas,
+			newReplicas: 0,
+			newTrafficPercent: 0,
+			availableReplicas: normalizedPlan.replicas,
+			observedErrorPercent: 0,
+			readinessSeconds: 0,
+			rollbackSeconds: dataSafe ? 8 : 300,
+			dataSafe,
+			status,
+			safeToContinue: dataSafe
+		};
+		return {
+			...rolledBack,
+			message: describe(rolledBack)
+		};
+	}
+	const deployment = deploymentAt(normalizedPlan, Math.max(0, Math.min(TOTAL_STEPS, step)));
+	const candidateError = normalizedPlan.candidateHealth === "faulty" ? 12 : .4;
+	const observedErrorPercent = Number((deployment.newTrafficPercent / 100 * candidateError).toFixed(1));
+	const contractSafe = dataSafe || deployment.newTrafficPercent === 0;
+	const safeToContinue = observedErrorPercent <= 1 && contractSafe;
+	const resolvedStatus = deployment.step === TOTAL_STEPS ? "completed" : "running";
+	const snapshot = {
+		...deployment,
+		plan: normalizedPlan,
+		observedErrorPercent,
+		readinessSeconds: normalizedPlan.candidateHealth === "healthy" ? 12 : 28,
+		rollbackSeconds: !dataSafe ? 300 : normalizedPlan.strategy === "blue-green" ? 4 : normalizedPlan.strategy === "canary" ? 8 : 35,
+		dataSafe: contractSafe,
+		status: resolvedStatus,
+		safeToContinue
+	};
+	return {
+		...snapshot,
+		message: describe(snapshot)
+	};
+}
+function transitionRelease(current, command) {
+	if (command.type === "reset") return releaseSnapshot(current.plan);
+	if (command.type === "rollback") return releaseSnapshot(current.plan, current.step, "rolled-back");
+	if (current.status !== "running") return current;
+	return releaseSnapshot(current.plan, current.step + 1);
+}
+function createReleaseEngine(plan) {
+	let current = releaseSnapshot(plan);
+	return {
+		get state() {
+			return current;
+		},
+		dispatch(command) {
+			current = transitionRelease(current, command);
+			return current;
+		}
+	};
+}
+
+//#endregion
+export { createReleaseEngine, releaseSnapshot, transitionRelease };

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

@@ -0,0 +1,25 @@
+//#region src/networking/cloud/scaling.d.ts
+type LoadRoutingPolicy = "round-robin" | "least-connections";
+type BackendHealth = "healthy" | "unhealthy";
+interface BackendResult {
+  readonly id: number;
+  readonly health: BackendHealth;
+  readonly baselineConnections: number;
+  readonly assignedRps: number;
+  readonly utilizationPercent: number;
+}
+interface ServiceScalingResult {
+  readonly policy: LoadRoutingPolicy;
+  readonly incomingRps: number;
+  readonly instanceCapacityRps: number;
+  readonly healthyInstances: number;
+  readonly totalCapacityRps: number;
+  readonly backends: readonly BackendResult[];
+  readonly queued: number;
+  readonly dropped: number;
+  readonly delayMs: number;
+  readonly diagnosis: string;
+}
+declare function simulateServiceScaling(instances: number, incomingRps: number, policy: LoadRoutingPolicy, failedBackend: number | null, instanceCapacityRps?: number): ServiceScalingResult;
+//#endregion
+export { BackendHealth, BackendResult, LoadRoutingPolicy, ServiceScalingResult, simulateServiceScaling };

package/dist/networking/cloud/scaling.mjs

@@ -0,0 +1,65 @@
+import { queueAtTime } from "../queue.mjs";
+
+//#region src/networking/cloud/scaling.ts
+const BASELINE = [
+	12,
+	4,
+	9,
+	2
+];
+const baselineFor = (index) => BASELINE[index] ?? 0;
+function assignRoundRobin(count, incomingRps) {
+	const base = Math.floor(incomingRps / count);
+	const extra = incomingRps % count;
+	return Array.from({ length: count }, (_, index) => base + (index < extra ? 1 : 0));
+}
+function assignLeastConnections(active, incomingRps) {
+	const assigned = active.map(() => 0);
+	for (let request = 0; request < incomingRps; request += 1) {
+		let target = 0;
+		let lightest = Infinity;
+		active.forEach((connections, index) => {
+			const load = connections + assigned[index];
+			if (load < lightest) {
+				lightest = load;
+				target = index;
+			}
+		});
+		assigned[target] = assigned[target] + 1;
+	}
+	return assigned;
+}
+function simulateServiceScaling(instances, incomingRps, policy, failedBackend, instanceCapacityRps = 20) {
+	const count = Math.max(1, Math.min(4, Math.round(instances)));
+	const activeIndexes = Array.from({ length: count }, (_, index) => index).filter((index) => index !== failedBackend);
+	const healthyInstances = activeIndexes.length;
+	const baseline = activeIndexes.map(baselineFor);
+	const assigned = healthyInstances === 0 ? [] : policy === "round-robin" ? assignRoundRobin(healthyInstances, incomingRps) : assignLeastConnections(baseline, incomingRps);
+	const totalCapacityRps = healthyInstances * instanceCapacityRps;
+	const queue = queueAtTime(incomingRps, totalCapacityRps, 60, 2);
+	const backends = Array.from({ length: count }, (_, id) => {
+		const activeIndex = activeIndexes.indexOf(id);
+		const assignedRps = activeIndex < 0 ? 0 : assigned[activeIndex];
+		return {
+			id,
+			health: activeIndex < 0 ? "unhealthy" : "healthy",
+			baselineConnections: baselineFor(id),
+			assignedRps,
+			utilizationPercent: activeIndex < 0 ? 0 : Math.min(100, Math.round(assignedRps / instanceCapacityRps * 100))
+		};
+	});
+	const diagnosis = healthyInstances === 0 ? "No backend passes the health check, so the load balancer has no eligible target." : queue.dropped > 0 ? "Healthy capacity is exhausted and the finite waiting queue is full. Excess requests receive an overload response." : queue.queued > 0 ? "The service is reachable, but incoming work exceeds the combined capacity of healthy backends." : failedBackend !== null ? "The health check removes the failed backend; remaining instances absorb its traffic." : policy === "least-connections" ? "New work goes to the backend with the fewest active and newly assigned connections." : "New work rotates across every healthy backend in order.";
+	return {
+		policy,
+		incomingRps,
+		instanceCapacityRps,
+		healthyInstances,
+		totalCapacityRps,
+		backends,
+		...queue,
+		diagnosis
+	};
+}
+
+//#endregion
+export { simulateServiceScaling };

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

@@ -0,0 +1,39 @@
+//#region src/networking/cloud/secrets.d.ts
+type SecretStrategy = "embedded-static" | "single-current" | "dual-overlap";
+type ConsumerRefresh = "restart" | "reload";
+type RotationTrigger = "scheduled" | "leaked";
+type RotationPhase = "baseline" | "issue" | "publish" | "refresh" | "revoke";
+interface SecretRotationPlan {
+  strategy: SecretStrategy;
+  refresh: ConsumerRefresh;
+  trigger: RotationTrigger;
+  consumers: number;
+}
+interface SecretRotationSnapshot {
+  plan: SecretRotationPlan;
+  step: number;
+  phase: RotationPhase;
+  oldValid: boolean;
+  newValid: boolean;
+  storeVersion: "old" | "new";
+  oldConsumers: number;
+  newConsumers: number;
+  failedConsumers: number;
+  outageSeconds: number;
+  leakContained: boolean;
+  rotationComplete: boolean;
+  message: string;
+}
+type SecretRotationCommand = {
+  type: "advance";
+} | {
+  type: "reset";
+};
+declare function secretRotationSnapshot(plan: SecretRotationPlan, step?: number): SecretRotationSnapshot;
+declare function transitionSecretRotation(current: SecretRotationSnapshot, command: SecretRotationCommand): SecretRotationSnapshot;
+declare function createSecretRotationEngine(plan: SecretRotationPlan): {
+  readonly state: SecretRotationSnapshot;
+  dispatch(command: SecretRotationCommand): SecretRotationSnapshot;
+};
+//#endregion
+export { ConsumerRefresh, RotationPhase, RotationTrigger, SecretRotationCommand, SecretRotationPlan, SecretRotationSnapshot, SecretStrategy, createSecretRotationEngine, secretRotationSnapshot, transitionSecretRotation };

package/dist/networking/cloud/secrets.mjs

@@ -0,0 +1,68 @@
+//#region src/networking/cloud/secrets.ts
+const PHASES = [
+	"baseline",
+	"issue",
+	"publish",
+	"refresh",
+	"revoke"
+];
+const clampConsumers = (value) => Math.max(2, Math.min(6, Math.round(value)));
+function secretRotationSnapshot(plan, step = 0) {
+	const normalized = {
+		...plan,
+		consumers: clampConsumers(plan.consumers)
+	};
+	const currentStep = Math.max(0, Math.min(PHASES.length - 1, step));
+	const phase = PHASES[currentStep];
+	const staticSecret = normalized.strategy === "embedded-static";
+	const dual = normalized.strategy === "dual-overlap";
+	const issued = currentStep >= 1 && !staticSecret;
+	const published = currentStep >= 2 && !staticSecret;
+	const refreshed = currentStep >= 3 && !staticSecret;
+	const revoked = currentStep >= 4 && !staticSecret;
+	const oldValid = staticSecret || !issued || dual && !revoked;
+	const newValid = issued;
+	const oldConsumers = refreshed ? 0 : normalized.consumers;
+	const newConsumers = refreshed ? normalized.consumers : 0;
+	const oldClientsRejected = oldConsumers > 0 && !oldValid;
+	const failedConsumers = oldClientsRejected ? oldConsumers : 0;
+	const outageSeconds = staticSecret ? 0 : oldClientsRejected ? normalized.refresh === "restart" ? 45 : 8 : normalized.refresh === "restart" && phase === "refresh" ? 12 : 0;
+	const leakContained = normalized.trigger !== "leaked" || revoked;
+	const rotationComplete = revoked && newConsumers === normalized.consumers;
+	const message = staticSecret ? normalized.trigger === "leaked" ? "The leaked value is copied into deployments. There is no coordinated version to replace and revoke." : "The embedded value still works, but every copy extends the credential lifetime and makes emergency replacement manual." : oldClientsRejected ? "The service stopped accepting the old value before consumers loaded the new one, so valid workloads are denied." : phase === "issue" && dual ? "The service accepts old and new values during a bounded overlap window." : phase === "publish" ? "The manager now publishes the new version; consumers must refresh before the old value is revoked." : phase === "refresh" ? normalized.refresh === "restart" ? "Consumers loaded the new version through a restart, creating a small availability cost." : "Consumers reloaded the new version without replacing their processes." : rotationComplete ? "Every consumer uses the new version and the old value is revoked." : "The old version is current. Begin rotation by issuing a distinct new value.";
+	return {
+		plan: normalized,
+		step: currentStep,
+		phase,
+		oldValid,
+		newValid,
+		storeVersion: published ? "new" : "old",
+		oldConsumers,
+		newConsumers,
+		failedConsumers,
+		outageSeconds,
+		leakContained,
+		rotationComplete,
+		message
+	};
+}
+function transitionSecretRotation(current, command) {
+	if (command.type === "reset") return secretRotationSnapshot(current.plan);
+	if (current.plan.strategy === "embedded-static") return current;
+	return secretRotationSnapshot(current.plan, current.step + 1);
+}
+function createSecretRotationEngine(plan) {
+	let current = secretRotationSnapshot(plan);
+	return {
+		get state() {
+			return current;
+		},
+		dispatch(command) {
+			current = transitionSecretRotation(current, command);
+			return current;
+		}
+	};
+}
+
+//#endregion
+export { createSecretRotationEngine, secretRotationSnapshot, transitionSecretRotation };

package/dist/networking/cloud/server-deployment.d.mts

@@ -0,0 +1,29 @@
+//#region src/networking/cloud/server-deployment.d.ts
+type DeploymentScope = "lan" | "internet";
+type ServerFrontEnd = "direct" | "nginx";
+type DeploymentFault = "none" | "subnet" | "dns" | "forward" | "firewall" | "listener";
+type DeploymentStage = "client" | "dns" | "router" | "firewall" | "nginx" | "app";
+declare const DEPLOYMENT_STAGES: readonly DeploymentStage[];
+interface ServerDeploymentResult {
+  readonly scope: DeploymentScope;
+  readonly frontEnd: ServerFrontEnd;
+  readonly stages: readonly DeploymentStage[];
+  readonly stoppedAt: DeploymentStage | null;
+  readonly reached: boolean;
+  readonly clientAddress: string;
+  readonly serverAddress: string;
+  readonly prefix: number;
+  readonly publicAddress: string;
+  readonly hostname: string;
+  readonly publicPort: number;
+  readonly listenerPort: number;
+  readonly appPort: number;
+  readonly queued: number;
+  readonly dropped: number;
+  readonly delayMs: number;
+  readonly diagnosis: string;
+}
+declare function simulateServerDeployment(scope: DeploymentScope, frontEnd: ServerFrontEnd, fault: DeploymentFault, requestsPerSecond: number, appCapacityRps?: number): ServerDeploymentResult;
+declare function deploymentStageState(stage: DeploymentStage, current: number, result: ServerDeploymentResult): "idle" | "active" | "success" | "error";
+//#endregion
+export { DEPLOYMENT_STAGES, DeploymentFault, DeploymentScope, DeploymentStage, ServerDeploymentResult, ServerFrontEnd, deploymentStageState, simulateServerDeployment };

package/dist/networking/cloud/server-deployment.mjs

@@ -0,0 +1,72 @@
+import { queueAtTime } from "../queue.mjs";
+import { sameNetwork } from "../subnet.mjs";
+
+//#region src/networking/cloud/server-deployment.ts
+const DEPLOYMENT_STAGES = [
+	"client",
+	"dns",
+	"router",
+	"firewall",
+	"nginx",
+	"app"
+];
+const DIAGNOSIS = {
+	subnet: "The client and server disagree about the LAN boundary. Fix the address or prefix.",
+	dns: "The name does not resolve to this router’s public address.",
+	forward: "The router has no public-port to private-listener mapping.",
+	firewall: "The host firewall rejects the incoming service port.",
+	listener: "The packet reaches the host, but no process is listening on that port."
+};
+function simulateServerDeployment(scope, frontEnd, fault, requestsPerSecond, appCapacityRps = 30) {
+	const prefix = fault === "subnet" ? 30 : 24;
+	const clientAddress = "192.168.1.24";
+	const serverAddress = "192.168.1.20";
+	const lanReachable = sameNetwork(clientAddress, serverAddress, prefix) === true;
+	const publicPort = frontEnd === "nginx" ? 443 : 3e3;
+	const listenerPort = publicPort;
+	const appPort = 3e3;
+	const effectiveFault = scope === "lan" && fault !== "subnet" && fault !== "listener" ? "none" : fault;
+	const stages = scope === "lan" ? [
+		"client",
+		...frontEnd === "nginx" ? ["nginx"] : [],
+		"app"
+	] : frontEnd === "nginx" ? DEPLOYMENT_STAGES : [
+		"client",
+		"dns",
+		"router",
+		"firewall",
+		"app"
+	];
+	const stoppedAt = effectiveFault === "subnet" || !lanReachable ? "client" : effectiveFault === "dns" ? "dns" : effectiveFault === "forward" ? "router" : effectiveFault === "firewall" ? "firewall" : effectiveFault === "listener" ? frontEnd === "nginx" ? "nginx" : "app" : null;
+	const reached = stoppedAt === null;
+	const load = reached ? queueAtTime(requestsPerSecond, appCapacityRps, 40, 2) : queueAtTime(0, appCapacityRps, 40, 2);
+	return {
+		scope,
+		frontEnd,
+		stages,
+		stoppedAt,
+		reached,
+		clientAddress,
+		serverAddress,
+		prefix,
+		publicAddress: "203.0.113.18",
+		hostname: "lab.example",
+		publicPort,
+		listenerPort,
+		appPort,
+		...load,
+		diagnosis: stoppedAt ? DIAGNOSIS[effectiveFault] : load.dropped > 0 ? "The route works, but demand exceeds app capacity. Requests wait, then the finite queue rejects excess work." : load.queued > 0 ? "The service is reachable. Demand now exceeds app capacity, so response delay is growing." : frontEnd === "nginx" ? "Nginx accepts the public service port and forwards each request to the private app port." : "The app is exposed directly on its own listening port."
+	};
+}
+function deploymentStageState(stage, current, result) {
+	const index = result.stages.indexOf(stage);
+	if (index < 0) return "idle";
+	const stop = result.stoppedAt ? result.stages.indexOf(result.stoppedAt) : Infinity;
+	if (index === stop && current >= index) return "error";
+	if (index === current && index < stop) return "active";
+	if (index < current && index < stop) return "success";
+	return "idle";
+}
+
+//#endregion
+export { DEPLOYMENT_STAGES, deploymentStageState, simulateServerDeployment };

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

@@ -0,0 +1,16 @@
+//#region src/networking/cloud/storage.d.ts
+type CloudWorkload = "temporary-cache" | "boot-volume" | "user-uploads" | "shared-files" | "transactions";
+type CloudStorage = "instance-disk" | "block-volume" | "object-store" | "shared-file" | "database";
+interface StorageResult {
+  workload: CloudWorkload;
+  storage: CloudStorage;
+  fit: "good" | "tradeoff" | "wrong";
+  survivesReplacement: boolean;
+  sharedByInstances: boolean;
+  supportsTransactions: boolean;
+  access: string;
+  diagnosis: string;
+}
+declare function evaluateCloudStorage(workload: CloudWorkload, storage: CloudStorage): StorageResult;
+//#endregion
+export { CloudStorage, CloudWorkload, StorageResult, evaluateCloudStorage };

package/dist/networking/cloud/storage.mjs

@@ -0,0 +1,58 @@
+//#region src/networking/cloud/storage.ts
+const CAPABILITIES = {
+	"instance-disk": {
+		persistent: false,
+		shared: false,
+		transactions: false,
+		access: "local filesystem"
+	},
+	"block-volume": {
+		persistent: true,
+		shared: false,
+		transactions: false,
+		access: "mounted block device"
+	},
+	"object-store": {
+		persistent: true,
+		shared: true,
+		transactions: false,
+		access: "object key API"
+	},
+	"shared-file": {
+		persistent: true,
+		shared: true,
+		transactions: false,
+		access: "shared filesystem"
+	},
+	database: {
+		persistent: true,
+		shared: true,
+		transactions: true,
+		access: "query / transaction API"
+	}
+};
+const IDEAL = {
+	"temporary-cache": "instance-disk",
+	"boot-volume": "block-volume",
+	"user-uploads": "object-store",
+	"shared-files": "shared-file",
+	transactions: "database"
+};
+function evaluateCloudStorage(workload, storage) {
+	const c = CAPABILITIES[storage];
+	const fit = storage === IDEAL[workload] ? "good" : workload === "user-uploads" && storage === "shared-file" || workload === "shared-files" && storage === "object-store" || workload === "boot-volume" && storage === "instance-disk" ? "tradeoff" : "wrong";
+	const diagnosis = fit === "good" ? `${storage} matches the access and lifecycle required by ${workload}.` : fit === "tradeoff" ? `${storage} can hold the data, but its access or lifecycle semantics create an operational tradeoff.` : `${storage} does not provide the required durability, sharing, or data semantics for ${workload}.`;
+	return {
+		workload,
+		storage,
+		fit,
+		survivesReplacement: c.persistent,
+		sharedByInstances: c.shared,
+		supportsTransactions: c.transactions,
+		access: c.access,
+		diagnosis
+	};
+}
+
+//#endregion
+export { evaluateCloudStorage };

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

@@ -0,0 +1,18 @@
+//#region src/networking/cloud/vpc.d.ts
+type VpcScenario = "internet-to-web" | "internet-to-app" | "app-to-internet" | "db-to-internet" | "web-to-db";
+type VpcDesign = "segmented" | "all-public" | "no-egress" | "blocked-data";
+type VpcZone = "internet" | "public" | "private" | "isolated";
+interface VpcRouteResult {
+  readonly scenario: VpcScenario;
+  readonly design: VpcDesign;
+  readonly source: VpcZone;
+  readonly destination: VpcZone;
+  readonly route: readonly string[];
+  readonly allowed: boolean;
+  readonly publicExposure: readonly string[];
+  readonly decision: string;
+  readonly rule: string;
+}
+declare function planVpcRoute(scenario: VpcScenario, design: VpcDesign): VpcRouteResult;
+//#endregion
+export { VpcDesign, VpcRouteResult, VpcScenario, VpcZone, planVpcRoute };

package/dist/networking/cloud/vpc.mjs

@@ -0,0 +1,100 @@
+//#region src/networking/cloud/vpc.ts
+const ENDPOINTS = {
+	"internet-to-web": {
+		source: "internet",
+		destination: "public"
+	},
+	"internet-to-app": {
+		source: "internet",
+		destination: "private"
+	},
+	"app-to-internet": {
+		source: "private",
+		destination: "internet"
+	},
+	"db-to-internet": {
+		source: "isolated",
+		destination: "internet"
+	},
+	"web-to-db": {
+		source: "public",
+		destination: "isolated"
+	}
+};
+function planVpcRoute(scenario, design) {
+	const { source, destination } = ENDPOINTS[scenario];
+	const allPublic = design === "all-public";
+	let allowed = false;
+	let route = [source];
+	let rule = "no matching route";
+	let decision = "No route carries this traffic to its destination.";
+	if (scenario === "internet-to-web") {
+		allowed = true;
+		route = [
+			"internet",
+			"internet gateway",
+			"public"
+		];
+		rule = "0.0.0.0/0 ↔ internet gateway";
+		decision = "The public subnet has an internet-gateway route, a public endpoint, and an ingress rule for the service.";
+	} else if (scenario === "internet-to-app") {
+		allowed = allPublic;
+		route = allPublic ? [
+			"internet",
+			"internet gateway",
+			"private"
+		] : ["internet", "internet gateway"];
+		rule = allPublic ? "0.0.0.0/0 ↔ internet gateway" : "private subnet has no inbound internet target";
+		decision = allPublic ? "The app tier was made public, so internet clients can address it directly." : "The private app tier has no direct public endpoint; clients must enter through the public service tier.";
+	} else if (scenario === "app-to-internet") {
+		allowed = design !== "no-egress";
+		route = allPublic ? [
+			"private",
+			"internet gateway",
+			"internet"
+		] : allowed ? [
+			"private",
+			"NAT gateway",
+			"internet gateway",
+			"internet"
+		] : ["private"];
+		rule = allPublic ? "0.0.0.0/0 → internet gateway" : allowed ? "0.0.0.0/0 → NAT gateway" : "no default route";
+		decision = allPublic ? "The app tier reaches the internet directly and is no longer private." : allowed ? "The NAT gateway provides outbound translation without making the app an inbound public target." : "Without a default route, the app cannot fetch updates or reach external APIs.";
+	} else if (scenario === "db-to-internet") {
+		allowed = allPublic;
+		route = allPublic ? [
+			"isolated",
+			"internet gateway",
+			"internet"
+		] : ["isolated"];
+		rule = allPublic ? "0.0.0.0/0 → internet gateway" : "local VPC route only";
+		decision = allPublic ? "The database subnet has been given direct internet routing, increasing exposure." : "The isolated data tier has no default internet route.";
+	} else {
+		allowed = design !== "blocked-data";
+		route = [
+			"public",
+			"local VPC route",
+			"isolated"
+		];
+		rule = allowed ? "10.20.0.0/16 → local; app port allowed" : "local route exists; firewall denies app-to-data port";
+		decision = allowed ? "Local VPC routing connects the subnets, while the data firewall admits only the required application traffic." : "A route exists, but the data-tier firewall still denies the connection.";
+	}
+	return {
+		scenario,
+		design,
+		source,
+		destination,
+		route,
+		allowed,
+		publicExposure: allPublic ? [
+			"web",
+			"app",
+			"database"
+		] : ["web"],
+		decision,
+		rule
+	};
+}
+
+//#endregion
+export { planVpcRoute };

package/dist/networking/delivery.d.mts

@@ -0,0 +1,34 @@
+//#region src/networking/delivery.d.ts
+type DeliveryMode = "terrestrial" | "multicast" | "unicast";
+interface BroadcastDeliveryResult {
+  readonly mode: DeliveryMode;
+  readonly viewers: number;
+  readonly bitrateMbps: number;
+  readonly sourceStreams: number;
+  readonly segmentCopies: number;
+  readonly segmentMbps: number;
+  readonly returnPath: boolean;
+  readonly personalized: boolean;
+}
+declare function compareDelivery(mode: DeliveryMode, viewers: number, bitrateMbps: number): BroadcastDeliveryResult;
+type DeviceState = "online" | "offline";
+interface GroupDeliveryResult {
+  readonly delivered: number;
+  readonly queued: number;
+  readonly copies: number;
+}
+declare function deliverGroupMessage(recipients: number, devicesEach: number, offlineDevices: number): GroupDeliveryResult;
+interface LiveStreamResult {
+  readonly segmentSeconds: number;
+  readonly bufferSeconds: number;
+  readonly outageSeconds: number;
+  readonly startupSeconds: number;
+  readonly liveLatencySeconds: number;
+  readonly stallSeconds: number;
+  readonly bufferedThroughDrop: boolean;
+}
+declare function simulateLiveStream(segmentSeconds: number, bufferSeconds: number, outageSeconds: number): LiveStreamResult;
+declare const STREAM_STAGES: readonly ["camera", "encoder", "origin", "cdn", "buffer", "viewer"];
+type StreamStage = (typeof STREAM_STAGES)[number];
+//#endregion
+export { BroadcastDeliveryResult, DeliveryMode, DeviceState, GroupDeliveryResult, LiveStreamResult, STREAM_STAGES, StreamStage, compareDelivery, deliverGroupMessage, simulateLiveStream };