@classytic/stage 0.2.0 → 0.4.0

package/dist/networking/cloud/access.mjs

@@ -0,0 +1,95 @@
+//#region src/networking/cloud/access.ts
+const RESOURCES = [
+	"orders",
+	"payments",
+	"objects"
+];
+const ACTIONS = [
+	"read",
+	"write",
+	"delete"
+];
+const REQUIRED = {
+	"checkout-api": [
+		{
+			resource: "orders",
+			action: "read"
+		},
+		{
+			resource: "orders",
+			action: "write"
+		},
+		{
+			resource: "payments",
+			action: "write"
+		}
+	],
+	"report-job": [{
+		resource: "orders",
+		action: "read"
+	}, {
+		resource: "payments",
+		action: "read"
+	}],
+	"backup-job": [{
+		resource: "objects",
+		action: "read"
+	}, {
+		resource: "objects",
+		action: "write"
+	}]
+};
+const keyOf = ({ resource, action }) => `${resource}:${action}`;
+const everyPermission = () => RESOURCES.flatMap((resource) => ACTIONS.map((action) => ({
+	resource,
+	action
+})));
+function grants(workload, design) {
+	if (design === "least-privilege") return [...REQUIRED[workload]];
+	return everyPermission();
+}
+function evaluateWorkloadAccess(workload, design, incident) {
+	const required = [...REQUIRED[workload]];
+	const granted = grants(workload, design);
+	const requiredKeys = new Set(required.map(keyOf));
+	const grantedKeys = new Set(granted.map(keyOf));
+	const attempted = incident === "normal" ? required : everyPermission();
+	const resources = RESOURCES.map((resource) => {
+		const resourceRequired = required.filter((permission) => permission.resource === resource).map(({ action }) => action);
+		const resourceGranted = granted.filter((permission) => permission.resource === resource).map(({ action }) => action);
+		const resourceAttempted = attempted.filter((permission) => permission.resource === resource).map(({ action }) => action);
+		return {
+			resource,
+			required: resourceRequired,
+			granted: resourceGranted,
+			attempted: resourceAttempted,
+			allowed: resourceAttempted.filter((action) => grantedKeys.has(`${resource}:${action}`)),
+			denied: resourceAttempted.filter((action) => !grantedKeys.has(`${resource}:${action}`))
+		};
+	});
+	const taskWorks = required.every((permission) => grantedKeys.has(keyOf(permission)));
+	const excessPermissions = granted.filter((permission) => !requiredKeys.has(keyOf(permission))).length;
+	const identity = design === "shared-admin-key" ? "shared-key" : "workload-identity";
+	const attributable = identity === "workload-identity";
+	const leastPrivilege = taskWorks && excessPermissions === 0 && attributable;
+	const exposedPermissions = incident === "compromised" ? granted.length : required.length;
+	const message = !taskWorks ? "The workload cannot complete its intended task because a required permission is missing." : incident === "compromised" && excessPermissions > 0 ? `The task needed ${required.length} permissions, but compromise exposes ${granted.length}. Remove ${excessPermissions} unnecessary grants.` : incident === "compromised" ? `The identity is compromised, but policy confines it to the ${required.length} permissions its task already required.` : !attributable ? "The task works, but every workload shares one credential, so requests cannot be attributed or revoked independently." : excessPermissions > 0 ? "The workload has its own identity, but its broad role still permits unrelated actions." : "The workload has a distinct identity and only the permissions required for its task.";
+	return {
+		workload,
+		design,
+		incident,
+		identity,
+		attributable,
+		requiredPermissions: required.length,
+		grantedPermissions: granted.length,
+		excessPermissions,
+		exposedPermissions,
+		taskWorks,
+		leastPrivilege,
+		resources,
+		message
+	};
+}
+
+//#endregion
+export { evaluateWorkloadAccess };

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

@@ -0,0 +1,43 @@
+//#region src/networking/cloud/containers.d.ts
+/**
+ * Package once, run repeatably: what a deployment artifact actually guarantees.
+ *
+ * Three things are deliberately kept apart here, because conflating them is the misconception the
+ * lab exists to break. Whether every replica runs the SAME BITS is a property of the artifact's
+ * identity. Whether a replica can be thrown away and replaced is a property of how it was installed.
+ * Whether the service survives that replacement is a property of where its state lives. A learner
+ * who fixes only the first still loses data on the next deploy.
+ */
+type Artifact = "host-install" | "image-tag" | "image-digest";
+type StatePlacement = "inside-container" | "external-service";
+type HostDrift = "same" | "different";
+/**
+ * What a replica is running, as a value rather than a sentence.
+ *
+ * The scene used to recover this by searching the prose for `'v3'` and `'19'`, which meant the
+ * drawing's idea of "this replica is wrong" was a substring match on a label. Naming the three
+ * outcomes lets the scene switch on them and lets the compiler check that it handled each.
+ */
+type ReplicaVersion = "expected" | "stale-runtime" | "moved-tag";
+/** Long form for a caption, short form for inside a replica box. Exhaustive by construction. */
+declare const VERSION_TEXT: Record<ReplicaVersion, {
+  full: string;
+  short: string;
+}>;
+interface ContainerDeploymentResult {
+  artifact: Artifact;
+  state: StatePlacement;
+  drift: HostDrift;
+  replicas: number;
+  /** What each replica ended up running, in replica order. */
+  versions: ReplicaVersion[];
+  consistent: boolean;
+  replaceable: boolean;
+  durable: boolean;
+  capacity: number;
+  startupSeconds: number;
+  diagnosis: string;
+}
+declare function evaluateContainerDeployment(artifact: Artifact, state: StatePlacement, drift: HostDrift, replicas: number): ContainerDeploymentResult;
+//#endregion
+export { Artifact, ContainerDeploymentResult, HostDrift, ReplicaVersion, StatePlacement, VERSION_TEXT, evaluateContainerDeployment };

package/dist/networking/cloud/containers.mjs

@@ -0,0 +1,54 @@
+//#region src/networking/cloud/containers.ts
+/** Long form for a caption, short form for inside a replica box. Exhaustive by construction. */
+const VERSION_TEXT = {
+	expected: {
+		full: "runtime 20 + app v2",
+		short: "v2"
+	},
+	"stale-runtime": {
+		full: "runtime 19 + app v2",
+		short: "r19"
+	},
+	"moved-tag": {
+		full: "tag moved → v3",
+		short: "v3"
+	}
+};
+/** What a single replica ends up running, given the artifact it was launched from. */
+function versionFor(artifact, drift, index, count) {
+	if (artifact === "host-install" && drift === "different" && index > 0) return "stale-runtime";
+	if (artifact === "image-tag" && drift === "different" && index === count - 1) return "moved-tag";
+	return "expected";
+}
+function evaluateContainerDeployment(artifact, state, drift, replicas) {
+	const count = Math.max(1, Math.min(4, Math.round(replicas)));
+	const versions = Array.from({ length: count }, (_, i) => versionFor(artifact, drift, i, count));
+	/**
+	* Consistency is READ OFF the replicas rather than predicted alongside them.
+	*
+	* It used to be its own expression (`digest || (tag && no drift)`), which could disagree with the
+	* versions the scene draws, and did: a host installation with no drift produces four identical
+	* replicas and was still reported inconsistent. That also made the host-install branch of the
+	* diagnosis below unreachable, which is how the contradiction stayed hidden. One replica cannot
+	* differ from itself, and this now says so.
+	*/
+	const consistent = versions.every((version) => version === versions[0]);
+	const replaceable = artifact !== "host-install";
+	const durable = state === "external-service";
+	return {
+		artifact,
+		state,
+		drift,
+		replicas: count,
+		versions,
+		consistent,
+		replaceable,
+		durable,
+		capacity: count * 100,
+		startupSeconds: artifact === "host-install" ? 90 : artifact === "image-tag" ? 14 : 10,
+		diagnosis: !consistent ? artifact === "host-install" ? "Replicas were installed by a procedure, and the hosts were not identical, so they no longer run the same bits." : "Instances launched from the same name do not run the same bits. Pin an immutable image digest." : !durable ? "The process is repeatable, but replacing it deletes state stored inside its writable layer." : artifact === "host-install" ? "It works today because these hosts happen to match. Nothing enforces that, and a rebuilt host will drift." : "Every replica starts from the same immutable artifact and keeps durable state outside the replaceable process."
+	};
+}
+
+//#endregion
+export { VERSION_TEXT, evaluateContainerDeployment };

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

@@ -0,0 +1,17 @@
+//#region src/networking/cloud/edge.d.ts
+type CachePolicy = "disabled" | "short-ttl" | "long-ttl";
+type OriginState = "unchanged" | "updated";
+interface EdgeResult {
+  viewers: number;
+  policy: CachePolicy;
+  originState: OriginState;
+  edgeHits: number;
+  originRequests: number;
+  hitRatio: number;
+  averageLatencyMs: number;
+  staleResponses: number;
+  diagnosis: string;
+}
+declare function simulateEdgeCache(viewers: number, policy: CachePolicy, originState: OriginState): EdgeResult;
+//#endregion
+export { CachePolicy, EdgeResult, OriginState, simulateEdgeCache };

package/dist/networking/cloud/edge.mjs

@@ -0,0 +1,31 @@
+//#region src/networking/cloud/edge.ts
+function simulateEdgeCache(viewers, policy, originState) {
+	const audience = Math.max(1, Math.round(viewers));
+	const edges = 3;
+	let edgeHits = 0, originRequests = audience, staleResponses = 0;
+	if (policy !== "disabled") {
+		originRequests = Math.min(edges, audience);
+		edgeHits = audience - originRequests;
+		if (originState === "updated" && policy === "short-ttl") {
+			originRequests = Math.min(edges * 2, audience);
+			edgeHits = audience - originRequests;
+		} else if (originState === "updated" && policy === "long-ttl") staleResponses = edgeHits;
+	}
+	const hitRatio = Math.round(edgeHits / audience * 100);
+	const averageLatencyMs = Math.round((edgeHits * 25 + originRequests * 180) / audience);
+	const diagnosis = policy === "disabled" ? "Every viewer crosses the long path to the origin." : staleResponses ? `${staleResponses} viewers receive the cached old version until expiry or invalidation.` : originState === "updated" && policy === "short-ttl" ? "Edges revalidate sooner, increasing origin work while reducing stale delivery." : `Edge caches serve ${edgeHits} repeated requests close to viewers and spare the origin.`;
+	return {
+		viewers: audience,
+		policy,
+		originState,
+		edgeHits,
+		originRequests,
+		hitRatio,
+		averageLatencyMs,
+		staleResponses,
+		diagnosis
+	};
+}
+
+//#endregion
+export { simulateEdgeCache };

package/dist/networking/cloud/failure-domains.d.mts

@@ -0,0 +1,19 @@
+//#region src/networking/cloud/failure-domains.d.ts
+type Placement = "single-zone" | "multi-zone" | "multi-region";
+type FailureScope = "instance" | "zone" | "region";
+type DataPlacement = "single-copy" | "multi-zone-copy" | "multi-region-copy";
+interface FailureDomainResult {
+  placement: Placement;
+  failure: FailureScope;
+  data: DataPlacement;
+  appCopies: number;
+  survivingApps: number;
+  serviceAvailable: boolean;
+  dataAvailable: boolean;
+  crossRegion: boolean;
+  recovery: string;
+  diagnosis: string;
+}
+declare function simulateFailureDomains(placement: Placement, failure: FailureScope, data: DataPlacement): FailureDomainResult;
+//#endregion
+export { DataPlacement, FailureDomainResult, FailureScope, Placement, simulateFailureDomains };

package/dist/networking/cloud/failure-domains.mjs

@@ -0,0 +1,22 @@
+//#region src/networking/cloud/failure-domains.ts
+function simulateFailureDomains(placement, failure, data) {
+	const appCopies = placement === "single-zone" ? 1 : placement === "multi-zone" ? 2 : 4;
+	const survivingApps = Math.max(0, appCopies - (failure === "instance" ? 1 : failure === "zone" ? placement === "single-zone" ? 1 : 1 : placement === "multi-region" ? 2 : appCopies));
+	const serviceAvailable = survivingApps > 0;
+	const dataAvailable = data === "multi-region-copy" || data === "multi-zone-copy" && failure !== "region" || data === "single-copy" && failure === "instance";
+	return {
+		placement,
+		failure,
+		data,
+		appCopies,
+		survivingApps,
+		serviceAvailable,
+		dataAvailable,
+		crossRegion: placement === "multi-region",
+		recovery: !serviceAvailable ? "restore or redeploy compute" : !dataAvailable ? "promote or restore durable data" : "route traffic to healthy capacity",
+		diagnosis: !serviceAvailable ? "The failure removed every application copy in the affected placement." : !dataAvailable ? "Compute survives, but the service cannot operate because its only usable data copy is lost." : failure === "region" && placement === "multi-region" ? "The second Region continues serving because compute and data were independently replicated there." : "The remaining failure domain continues serving and the health-aware entry point shifts traffic."
+	};
+}
+
+//#endregion
+export { simulateFailureDomains };

package/dist/networking/cloud/geo-routing.d.mts

@@ -0,0 +1,22 @@
+//#region src/networking/cloud/geo-routing.d.ts
+type ShopperLocation = "dhaka" | "frankfurt" | "new-york";
+type CustomerContext = "guest" | "account-bd" | "account-de" | "selected-us";
+type GeoRoutingPolicy = "nearest" | "home-market";
+interface GeoMarketResult {
+  location: ShopperLocation;
+  context: CustomerContext;
+  policy: GeoRoutingPolicy;
+  endpoint: string;
+  endpointLatencyMs: number;
+  market: string;
+  currency: string;
+  catalog: string;
+  taxBasis: string;
+  locationHint: string;
+  authority: string;
+  crossBorder: boolean;
+  diagnosis: string;
+}
+declare function resolveGeoMarket(location: ShopperLocation, context: CustomerContext, policy: GeoRoutingPolicy): GeoMarketResult;
+//#endregion
+export { CustomerContext, GeoMarketResult, GeoRoutingPolicy, ShopperLocation, resolveGeoMarket };

package/dist/networking/cloud/geo-routing.mjs

@@ -0,0 +1,64 @@
+//#region src/networking/cloud/geo-routing.ts
+const places = {
+	dhaka: {
+		endpoint: "Singapore edge",
+		latency: 42,
+		hint: "Bangladesh"
+	},
+	frankfurt: {
+		endpoint: "Frankfurt edge",
+		latency: 18,
+		hint: "Germany"
+	},
+	"new-york": {
+		endpoint: "Virginia edge",
+		latency: 24,
+		hint: "United States"
+	}
+};
+const markets = {
+	Bangladesh: {
+		currency: "BDT",
+		catalog: "Bangladesh catalog",
+		tax: "delivery market"
+	},
+	Germany: {
+		currency: "EUR",
+		catalog: "EU catalog",
+		tax: "delivery market"
+	},
+	"United States": {
+		currency: "USD",
+		catalog: "US catalog",
+		tax: "delivery market"
+	}
+};
+function resolveGeoMarket(location, context, policy) {
+	const place = places[location];
+	const explicit = context === "account-bd" ? "Bangladesh" : context === "account-de" ? "Germany" : context === "selected-us" ? "United States" : null;
+	const market = explicit ?? place.hint;
+	const endpoint = policy === "nearest" ? place.endpoint : market === "Bangladesh" ? "Singapore edge" : market === "Germany" ? "Frankfurt edge" : "Virginia edge";
+	const endpointLatencyMs = policy === "nearest" ? place.latency : place.endpoint === endpoint ? place.latency : place.latency + 95;
+	const rules = markets[market];
+	const authority = explicit ? context === "selected-us" ? "shopper selection" : "signed-in account" : "network-location hint";
+	const crossBorder = place.hint !== market;
+	const diagnosis = crossBorder ? `The request enters through ${endpoint}, while explicit ${authority} keeps the ${market} market. Network location does not overwrite customer intent.` : `The request enters through ${endpoint}. ${explicit ? "Explicit customer context" : "A location hint"} selects the ${market} market independently.`;
+	return {
+		location,
+		context,
+		policy,
+		endpoint,
+		endpointLatencyMs,
+		market,
+		currency: rules.currency,
+		catalog: rules.catalog,
+		taxBasis: rules.tax,
+		locationHint: place.hint,
+		authority,
+		crossBorder,
+		diagnosis
+	};
+}
+
+//#endregion
+export { resolveGeoMarket };

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

@@ -0,0 +1,18 @@
+import { AccessDesign, AccessIncident, AccessSnapshot, CloudResource, Permission, ResourceAccess, ResourceAction, WorkloadKind, evaluateWorkloadAccess } from "./access.mjs";
+import { Artifact, ContainerDeploymentResult, HostDrift, ReplicaVersion, StatePlacement, VERSION_TEXT, evaluateContainerDeployment } from "./containers.mjs";
+import { CachePolicy, EdgeResult, OriginState, simulateEdgeCache } from "./edge.mjs";
+import { DataPlacement, FailureDomainResult, FailureScope, Placement, simulateFailureDomains } from "./failure-domains.mjs";
+import { CustomerContext, GeoMarketResult, GeoRoutingPolicy, ShopperLocation, resolveGeoMarket } from "./geo-routing.mjs";
+import { 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 } from "./inference.mjs";
+import { InferenceCondition, InferenceDegradationPolicy, InferenceReliabilityResult, InferenceRisk, InferenceSli, simulateInferenceReliability } from "./inference-reliability.mjs";
+import { DriftResolution, ExternalChange, InfrastructureCommand, InfrastructureIntent, InfrastructurePhase, InfrastructurePlan, InfrastructureShape, InfrastructureSnapshot, createInfrastructureEngine, infrastructureSnapshot, transitionInfrastructure } from "./infrastructure.mjs";
+import { DependencyState, SloIncidentResult, SloTarget, Telemetry, observeService } from "./observability.mjs";
+import { ClusterCapacity, ClusterFailure, OrchestrationResult, ReleaseState, reconcileWorkload } from "./orchestration.mjs";
+import { Incident, RecoveryResult, RecoveryStrategy, WriteLoad, evaluateRecovery } from "./recovery.mjs";
+import { CandidateHealth, DataCompatibility, ReleaseCommand, ReleasePlan, ReleaseSnapshot, ReleaseStatus, ReleaseStrategy, createReleaseEngine, releaseSnapshot, transitionRelease } from "./releases.mjs";
+import { BackendHealth, BackendResult, LoadRoutingPolicy, ServiceScalingResult, simulateServiceScaling } from "./scaling.mjs";
+import { ConsumerRefresh, RotationPhase, RotationTrigger, SecretRotationCommand, SecretRotationPlan, SecretRotationSnapshot, SecretStrategy, createSecretRotationEngine, secretRotationSnapshot, transitionSecretRotation } from "./secrets.mjs";
+import { DEPLOYMENT_STAGES, DeploymentFault, DeploymentScope, DeploymentStage, ServerDeploymentResult, ServerFrontEnd, deploymentStageState, simulateServerDeployment } from "./server-deployment.mjs";
+import { CloudStorage, CloudWorkload, StorageResult, evaluateCloudStorage } from "./storage.mjs";
+import { VpcDesign, VpcRouteResult, VpcScenario, VpcZone, planVpcRoute } from "./vpc.mjs";
+export { AccessDesign, AccessIncident, AccessSnapshot, Artifact, BackendHealth, BackendResult, BatchSize, CachePolicy, CandidateHealth, CloudResource, CloudStorage, CloudWorkload, ClusterCapacity, ClusterFailure, ConsumerRefresh, ContainerDeploymentResult, ContextSize, CustomerContext, DEPLOYMENT_STAGES, DataCompatibility, DataPlacement, DependencyState, DeploymentFault, DeploymentScope, DeploymentStage, DistributedInferenceResult, DistributedStrategy, DriftResolution, EdgeResult, ExternalChange, FailureDomainResult, FailureScope, GeoMarketResult, GeoRoutingPolicy, GpuCount, GpuInterconnect, GpuMemory, HostDrift, Incident, InferenceCapacityResult, InferenceCondition, InferenceDegradationPolicy, InferenceReliabilityResult, InferenceRequestResult, InferenceRisk, InferenceScheduler, InferenceSli, InferenceWorkloadMix, InfrastructureCommand, InfrastructureIntent, InfrastructurePhase, InfrastructurePlan, InfrastructureShape, InfrastructureSnapshot, LoadRoutingPolicy, ModelRoutingPolicy, ModelRoutingResult, ModelSize, OrchestrationResult, OriginState, OutputTokens, Permission, Placement, Precision, PrefixCacheResult, PrefixCacheScope, PrefixCacheState, PrefixRequester, PrefixTokens, PromptTokens, RecoveryResult, RecoveryStrategy, ReleaseCommand, ReleasePlan, ReleaseSnapshot, ReleaseState, ReleaseStatus, ReleaseStrategy, ReplicaVersion, ResourceAccess, ResourceAction, ResponseQualityTarget, RotationPhase, RotationTrigger, SecretRotationCommand, SecretRotationPlan, SecretRotationSnapshot, SecretStrategy, ServerDeploymentResult, ServerFrontEnd, ServiceScalingResult, ShopperLocation, SloIncidentResult, SloTarget, StatePlacement, StorageResult, Telemetry, UniquePromptTokens, VERSION_TEXT, VpcDesign, VpcRouteResult, VpcScenario, VpcZone, WorkloadKind, WriteLoad, createInfrastructureEngine, createReleaseEngine, createSecretRotationEngine, deploymentStageState, evaluateCloudStorage, evaluateContainerDeployment, evaluateRecovery, evaluateWorkloadAccess, infrastructureSnapshot, observeService, planInference, planVpcRoute, reconcileWorkload, releaseSnapshot, resolveGeoMarket, secretRotationSnapshot, simulateDistributedInference, simulateEdgeCache, simulateFailureDomains, simulateInferenceReliability, simulateInferenceRequest, simulateModelRouting, simulatePrefixCache, simulateServerDeployment, simulateServiceScaling, transitionInfrastructure, transitionRelease, transitionSecretRotation };

package/dist/networking/cloud/index.mjs

@@ -0,0 +1,19 @@
+import { evaluateWorkloadAccess } from "./access.mjs";
+import { VERSION_TEXT, evaluateContainerDeployment } from "./containers.mjs";
+import { simulateEdgeCache } from "./edge.mjs";
+import { simulateFailureDomains } from "./failure-domains.mjs";
+import { resolveGeoMarket } from "./geo-routing.mjs";
+import { planInference, simulateDistributedInference, simulateInferenceRequest, simulateModelRouting, simulatePrefixCache } from "./inference.mjs";
+import { simulateInferenceReliability } from "./inference-reliability.mjs";
+import { createInfrastructureEngine, infrastructureSnapshot, transitionInfrastructure } from "./infrastructure.mjs";
+import { observeService } from "./observability.mjs";
+import { reconcileWorkload } from "./orchestration.mjs";
+import { evaluateRecovery } from "./recovery.mjs";
+import { createReleaseEngine, releaseSnapshot, transitionRelease } from "./releases.mjs";
+import { simulateServiceScaling } from "./scaling.mjs";
+import { createSecretRotationEngine, secretRotationSnapshot, transitionSecretRotation } from "./secrets.mjs";
+import { DEPLOYMENT_STAGES, deploymentStageState, simulateServerDeployment } from "./server-deployment.mjs";
+import { evaluateCloudStorage } from "./storage.mjs";
+import { planVpcRoute } from "./vpc.mjs";
+
+export { DEPLOYMENT_STAGES, VERSION_TEXT, createInfrastructureEngine, createReleaseEngine, createSecretRotationEngine, deploymentStageState, evaluateCloudStorage, evaluateContainerDeployment, evaluateRecovery, evaluateWorkloadAccess, infrastructureSnapshot, observeService, planInference, planVpcRoute, reconcileWorkload, releaseSnapshot, resolveGeoMarket, secretRotationSnapshot, simulateDistributedInference, simulateEdgeCache, simulateFailureDomains, simulateInferenceReliability, simulateInferenceRequest, simulateModelRouting, simulatePrefixCache, simulateServerDeployment, simulateServiceScaling, transitionInfrastructure, transitionRelease, transitionSecretRotation };

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

@@ -0,0 +1,30 @@
+//#region src/networking/cloud/inference-reliability.d.ts
+type InferenceCondition = "healthy" | "overloaded" | "primary-unavailable";
+type InferenceDegradationPolicy = "retry-primary" | "fallback-small" | "shed-load";
+type InferenceRisk = "routine" | "high-stakes";
+type InferenceSli = "transport" | "useful";
+interface InferenceReliabilityResult {
+  condition: InferenceCondition;
+  policy: InferenceDegradationPolicy;
+  risk: InferenceRisk;
+  sli: InferenceSli;
+  requests: number;
+  returnedResponses: number;
+  degradedResponses: number;
+  rejectedRequests: number;
+  unsafeResponses: number;
+  lateResponses: number;
+  usefulResponses: number;
+  transportRatePercent: number;
+  usefulRatePercent: number;
+  measuredRatePercent: number;
+  objectivePercent: number;
+  meetsObjective: boolean;
+  p95LatencyMs: number;
+  outcome: "healthy" | "safe-degradation" | "quality-hidden" | "unavailable";
+  diagnosis: string;
+}
+/** Models 100 requests so returned, rejected, late and unsafe outcomes stay explicit and additive. */
+declare function simulateInferenceReliability(condition: InferenceCondition, policy: InferenceDegradationPolicy, risk: InferenceRisk, sli: InferenceSli): InferenceReliabilityResult;
+//#endregion
+export { InferenceCondition, InferenceDegradationPolicy, InferenceReliabilityResult, InferenceRisk, InferenceSli, simulateInferenceReliability };

package/dist/networking/cloud/inference-reliability.mjs

@@ -0,0 +1,76 @@
+//#region src/networking/cloud/inference-reliability.ts
+/** Models 100 requests so returned, rejected, late and unsafe outcomes stay explicit and additive. */
+function simulateInferenceReliability(condition, policy, risk, sli) {
+	const requests = 100;
+	let returnedResponses = 100;
+	let degradedResponses = 0;
+	let rejectedRequests = 0;
+	let lateResponses = 0;
+	let p95LatencyMs = 650;
+	if (condition === "overloaded") if (policy === "retry-primary") {
+		returnedResponses = 92;
+		rejectedRequests = 8;
+		lateResponses = 30;
+		p95LatencyMs = 4800;
+	} else if (policy === "fallback-small") {
+		returnedResponses = 99;
+		degradedResponses = 55;
+		rejectedRequests = 1;
+		lateResponses = 2;
+		p95LatencyMs = 1200;
+	} else {
+		returnedResponses = 75;
+		rejectedRequests = 25;
+		p95LatencyMs = 600;
+	}
+	else if (condition === "primary-unavailable") if (policy === "retry-primary") {
+		returnedResponses = 18;
+		rejectedRequests = 82;
+		lateResponses = 10;
+		p95LatencyMs = 8e3;
+	} else if (policy === "fallback-small") {
+		returnedResponses = 98;
+		degradedResponses = 98;
+		rejectedRequests = 2;
+		lateResponses = 2;
+		p95LatencyMs = 1e3;
+	} else {
+		returnedResponses = 60;
+		rejectedRequests = 40;
+		p95LatencyMs = 450;
+	}
+	const baselineUnsafe = risk === "routine" ? 2 : 4;
+	const fallbackUnsafe = condition === "healthy" ? baselineUnsafe : risk === "routine" ? condition === "overloaded" ? 5 : 8 : condition === "overloaded" ? 24 : 32;
+	const unsafeResponses = Math.min(returnedResponses - lateResponses, policy === "fallback-small" ? fallbackUnsafe : Math.min(baselineUnsafe, returnedResponses));
+	const usefulResponses = Math.max(0, returnedResponses - lateResponses - unsafeResponses);
+	const transportRatePercent = returnedResponses;
+	const usefulRatePercent = usefulResponses;
+	const measuredRatePercent = sli === "transport" ? transportRatePercent : usefulRatePercent;
+	const objectivePercent = 95;
+	const meetsObjective = measuredRatePercent >= objectivePercent;
+	const outcome = condition === "healthy" ? "healthy" : sli === "transport" && transportRatePercent >= objectivePercent && usefulRatePercent < objectivePercent ? "quality-hidden" : usefulResponses >= 70 && unsafeResponses <= 5 ? "safe-degradation" : "unavailable";
+	return {
+		condition,
+		policy,
+		risk,
+		sli,
+		requests,
+		returnedResponses,
+		degradedResponses,
+		rejectedRequests,
+		unsafeResponses,
+		lateResponses,
+		usefulResponses,
+		transportRatePercent,
+		usefulRatePercent,
+		measuredRatePercent,
+		objectivePercent,
+		meetsObjective,
+		p95LatencyMs,
+		outcome,
+		diagnosis: outcome === "quality-hidden" ? "The transport SLI passes while late or unsafe responses remain invisible to the objective." : outcome === "safe-degradation" ? "The service refuses some work to protect latency and response quality for the work it accepts." : outcome === "unavailable" ? policy === "retry-primary" ? "Retries amplify pressure or wait on a dependency that cannot recover inside the request deadline." : "This policy does not preserve enough useful outcomes for the selected workload risk." : "The primary path meets the modeled useful-response objective."
+	};
+}
+
+//#endregion
+export { simulateInferenceReliability };

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 };