@norskvideo/norsk-auto-manager 0.1.0

package/lib/src/knownCapabilities.js

@@ -0,0 +1,22 @@
+"use strict";
+// Standard capability names shipped with Norsk. Use these constants
+// rather than literal strings — typos in user code surface at compile
+// time rather than as silent placement misses.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KnownCapabilities = void 0;
+/** @public */
+exports.KnownCapabilities = {
+    /** Whole NVIDIA GPU, exclusive. For fractional, use requiredGpuCapacity. */
+    NvidiaGpu: "norsk.io/nvidia-gpu",
+    /** Intel Quick Sync Video — fixed-function media accelerator. */
+    IntelQsv: "norsk.io/intel-qsv",
+    /** Netint Quadra T1U accelerator. */
+    Quadra: "norsk.io/quadra",
+    /** Blackmagic DeckLink capture/playout card. */
+    Decklink: "norsk.io/decklink",
+    /** SMPTE ST 2110 capable NIC. */
+    St2110Nic: "norsk.io/st2110-nic",
+    /** Media eXchange Layer slot, provided by an MXL bridge NodeService. */
+    Mxl: "norsk.io/mxl",
+};
+//# sourceMappingURL=knownCapabilities.js.map

package/lib/src/placement.d.ts

@@ -0,0 +1,268 @@
+import { Bundle, BundleId, BundleJobSpec, Capability, NodeId, NodeInventory } from "./types";
+/** @public */
+export interface NodeView {
+    nodeId: NodeId;
+    poolName: string;
+    /**
+     * Which tier within the pool this node belongs to. Set from
+     * `tags["tier"]` at provision time for elastic tiers. Pre-registered
+     * cluster nodes carry no tier tag (undefined) and are treated as
+     * belonging to their pool's `fixed` tier — see `nodeMatchesTier`.
+     */
+    tierName?: string;
+    inventory: NodeInventory;
+    /** Jobs currently running on this node (or pending placement onto it). */
+    runningJobs: RunningJob[];
+    /** Topology key for the resilience sameAz rule. Cluster pools can leave undefined. */
+    az?: string;
+    /**
+     * Cloud / failure-domain key for the resilience sameCloud rule — the
+     * node's provider (e.g. "aws" / "oci" / "cluster"). Undefined when
+     * unknown; sameCloud then can't be evaluated against this node.
+     */
+    cloud?: string;
+    /** Hot spare flag (Phase C). Currently unused by hard-constraint filters. */
+    isHotSpare: boolean;
+}
+/** @public */
+export interface RunningJob {
+    bundleId: BundleId;
+    replicaIndex: number;
+    jobName: string;
+}
+/**
+ * A pool is an ordered list of capacity tiers. Placement walks the tiers
+ * in order (cheapest first) and takes the first that can satisfy the job
+ * — the tier order *is* the cost cascade (no cost weight in v1). The
+ * homogeneous single-cloud pool of before is just a one-tier pool.
+ *
+ * @public
+ */
+export interface PlacementPool {
+    name: string;
+    /** Ordered cheapest → most expensive. Placement tries them in order. */
+    tiers: PlacementTier[];
+}
+/**
+ * One homogeneous capacity segment within a pool: a single cloud/cluster
+ * kind + region with its own scale-out behaviour and candidate shapes.
+ *
+ * @public
+ */
+export interface PlacementTier {
+    /** Unique within the pool. Tagged onto provisioned nodes as `tags["tier"]`. */
+    name: string;
+    /**
+     * Cloud / local-servers kind. Used by AutoManager to decide which gRPC
+     * call to make when provisioning (createAwsNode vs createOciNode vs
+     * local-servers-tier placement, which uses startJob against an existing
+     * registered server).
+     */
+    kind: "aws" | "oci" | "local-servers";
+    /**
+     * For aws/oci elastic tiers: which region/availability-domain to
+     * provision into. Cluster tiers leave undefined.
+     */
+    region?: string;
+    packingStrategy: "binpack" | "spread";
+    scaleOut: "elastic" | "fixed";
+    /**
+     * For elastic tiers: shapes that can be provisioned on demand. For
+     * fixed tiers: typically empty (the tier consists of registered
+     * cluster nodes already in `inventory`).
+     */
+    candidateInstanceTypes: InstanceTypeOption[];
+    /**
+     * How long ahead of a scheduled job's `startDateTime` AutoManager
+     * should kick off placement, so the worker is ready to run by the
+     * requested time. Cluster tiers place against an existing running
+     * node (~instant) so the default is 0. Cloud tiers have to boot a
+     * fresh instance — defaults to 5 minutes; operators set per-tier
+     * when their boot time differs. AutoManager picks the maximum across
+     * the bundle pool's tiers (worst case — guarantees readiness
+     * regardless of which tier the placement engine settles on).
+     */
+    placementLeadMs?: number;
+    /**
+     * How nodes in this tier are purchased. `"spot"` requests interruptible
+     * spot-market capacity; `"reserved"` is an on-demand launch the operator
+     * knows is covered by a standing reservation (same AWS call as on-demand,
+     * but capped — see `maxNodes`). Defaults to `"on-demand"`.
+     */
+    launchMode?: LaunchMode;
+    /**
+     * Failure-domain reliability of this tier's capacity. Defaults to
+     * `"interruptible"` for spot, `"durable"` otherwise. Read by the
+     * resilience engine — an interruptible-tier primary with no durable
+     * backup is flagged degraded.
+     */
+    reliability?: Reliability;
+    /**
+     * Cap on the number of nodes this tier may hold (tier-wide, across
+     * bundles). The cost cascade spills to the next tier once the cap is
+     * reached. Used mainly for reserved tiers — exceeding the reservation
+     * count just bills as on-demand, defeating the point. Unset ⇒ no cap.
+     */
+    maxNodes?: number;
+}
+/** @public */
+export type LaunchMode = "on-demand" | "spot" | "reserved";
+/** @public */
+export type Reliability = "durable" | "interruptible";
+/** The tier's launch mode, defaulting to on-demand. @public */
+export declare function tierLaunchMode(tier: PlacementTier): LaunchMode;
+/** The tier's reliability — explicit, else interruptible for spot. @public */
+export declare function tierReliability(tier: PlacementTier): Reliability;
+/** Default placement lead time by tier kind. Cluster tiers place
+ *  against existing running nodes so we don't need lead. Cloud tiers
+ *  default to 5 minutes — typical EC2/OCI instance boot + image pull
+ *  budget; operators can override per-tier via PlacementTier. */
+export declare function defaultPlacementLeadMs(kind: PlacementTier["kind"]): number;
+/**
+ * Whether a node belongs to (pool, tier). Elastic nodes carry an explicit
+ * `tierName` (set from `tags["tier"]` at provision). Pre-registered cluster
+ * nodes carry no tier tag and are taken to belong to the pool's `fixed`
+ * tier — so a pool must have at most one fixed tier (enforced in
+ * settingsValidation) for this to be unambiguous.
+ *
+ * @public
+ */
+export declare function nodeMatchesTier(n: NodeView, pool: PlacementPool, tier: PlacementTier): boolean;
+/** @public */
+export interface InstanceTypeOption {
+    instanceType: string;
+    totalCapacity: number;
+    totalCores: number;
+    capabilities: Capability[];
+    /** GPUs we could provision a node with — for feasibility check. */
+    gpus?: {
+        totalCapacity: number;
+        model?: string;
+    }[];
+}
+/** @public */
+export interface RecoveryContext {
+    /** NodeIds the placement engine must skip (e.g., recently failed). */
+    excludeNodes: Set<NodeId>;
+    /** Reserved for Phase C — biases scoring toward hot spares. */
+    preferHotSpares: boolean;
+}
+/** @public */
+export interface PlacementInput {
+    bundle: Bundle;
+    job: BundleJobSpec;
+    replicaIndex: number;
+    inventory: NodeView[];
+    pools: Map<string, PlacementPool>;
+    recoveryContext?: RecoveryContext;
+}
+/** @public */
+/** Which anti-affinity flag(s) a backup placement couldn't honour. */
+export type ResilienceFlag = "sameNode" | "sameAz" | "sameCloud";
+/**
+ * Set on a backup placement that landed inside a failure domain its
+ * resilience policy asked to avoid (best-effort: no compliant node had
+ * capacity). The engine places it anyway and surfaces this so the
+ * operator knows the bundle's DR posture is currently reduced.
+ *
+ * @public
+ */
+export interface ResilienceDegradation {
+    violated: ResilienceFlag[];
+    /**
+     * Set when the primary landed on interruptible (spot) capacity with no
+     * durable backup — a single interruption takes the workload down. Surfaced
+     * so the operator can add a durable backup.
+     */
+    interruptiblePrimary?: boolean;
+}
+/** @public */
+export type PlacementResult = {
+    kind: "place";
+    nodeId: NodeId;
+    gpuIndex?: number;
+    pool: string;
+    tier: string;
+    degraded?: ResilienceDegradation;
+} | {
+    kind: "provision";
+    pool: string;
+    tier: string;
+    instanceType: string;
+    launchMode: LaunchMode;
+    degraded?: ResilienceDegradation;
+} | {
+    kind: "failure";
+    reason: PlacementFailureReason;
+};
+/** @public */
+export interface PlacementFailureReason {
+    code: "noCapacityInAnyPool" | "noConfiguredPools";
+    triedPools: string[];
+}
+/**
+ * Structured trace of a placement decision — one entry per pool
+ * attempted, with per-node filter outcomes and resulting scores. Used
+ * for "why did my job land here?" debugging.
+ *
+ * @public
+ */
+export interface PlacementTrace {
+    attempts: PoolAttempt[];
+    /** Final decision kind, mirroring PlacementResult.kind. */
+    decision: "place" | "provision" | "failure";
+}
+/** @public */
+export interface PoolAttempt {
+    pool: string;
+    /** Which tier of the pool this attempt covers. */
+    tier: string;
+    /** Total nodes considered in this pool before any filtering. */
+    initialCandidates: number;
+    /** Why each non-matching node was filtered out. Indexed by nodeId. */
+    filtered: {
+        nodeId: NodeId;
+        reason: FilterReason;
+    }[];
+    /** Nodes that survived all filters, with their assigned scores. */
+    scored: {
+        nodeId: NodeId;
+        score: number;
+    }[];
+    /** What this pool attempt produced. */
+    outcome: {
+        kind: "placed";
+        nodeId: NodeId;
+        gpuIndex?: number;
+    } | {
+        kind: "provisioned";
+        instanceType: string;
+    } | {
+        kind: "exhausted";
+    } | {
+        kind: "no-instance-type";
+    } | {
+        kind: "missing-pool";
+    };
+}
+/** @public */
+export type FilterReason = "wrong-pool" | "wrong-tier" | "excluded-recovery" | "unreachable" | "cordoned" | "missing-capability" | "insufficient-capacity" | "insufficient-cores" | "no-fitting-gpu" | "fails-intra-replica" | "fails-intra-az";
+/**
+ * Core placement function. Pure — no side effects, no I/O.
+ *
+ * @public
+ */
+export declare function place(input: PlacementInput): PlacementResult;
+/**
+ * Placement with a structured trace of every pool attempted and every
+ * node's filter outcome. AutoManager logs the trace via debuglog when
+ * placing; tests use it to assert on the precise reason a candidate
+ * was rejected.
+ *
+ * @public
+ */
+export declare function placeWithTrace(input: PlacementInput): {
+    result: PlacementResult;
+    trace: PlacementTrace;
+};
+//# sourceMappingURL=placement.d.ts.map