@norskvideo/norsk-auto-manager 0.1.0

package/src/types.ts

@@ -0,0 +1,346 @@
+// Type model for the AutoManager v1 design (see
+// .ai/steve/tasks/37-auto-manager-design.md). These are the new
+// scheduler-facing types — capabilities, capacity, bundles, replicas,
+// priority bands, node inventory. They sit alongside the existing
+// AutoManager types in automanager.ts (AutoJob, NodeSummary, AutoSettings)
+// which serve the older API surface; new code should prefer the types
+// here.
+
+import * as ManagerSdk from "@norskvideo/norsk-manager-sdk";
+import { ProductTemplateRef, JobId, NodeId, Role } from "@norskvideo/norsk-manager-sdk";
+
+// ----- IDs -------------------------------------------------------------
+
+/** @public */
+export type BundleId = string;
+/** @public */
+export type ServiceId = string;
+
+// ----- Capacity & cores (§3.1) -----------------------------------------
+
+/**
+ * Reference-workload-normalised compute units. The reference is real-time
+ * H.264 1080p30 libx264 preset `medium` single-stream. A node's
+ * `totalCapacity` is its score for that benchmark; a job's
+ * `requiredCapacity` is what it consumes against the same scale.
+ *
+ * @public
+ */
+export type Capacity = number;
+
+/**
+ * Integer count of CPU cores, used both for nodes (`totalCores`) and for
+ * jobs that need explicit cpuset pinning (`requiredCores`). Distinct from
+ * `Capacity` because pinning is about parallelism slicing, not throughput.
+ *
+ * @public
+ */
+export type CoreCount = number;
+
+// ----- GPU (§3.2) ------------------------------------------------------
+
+/**
+ * Per-device GPU pool. Each physical GPU on a node appears as its own
+ * `GpuResource` with a capacity score. Jobs request fractional capacity
+ * via `requiredGpuCapacity`; for whole-GPU exclusive use, request the
+ * `norsk.io/nvidia-gpu` capability instead (see §3.3).
+ *
+ * @public
+ */
+export interface GpuResource {
+  index: number;
+  model?: string;
+  totalCapacity: number;
+  reservedCapacity: number;
+  /** True if a whole-GPU exclusive job has taken this device. */
+  exclusivelyReserved: boolean;
+}
+
+// ----- Capabilities (§3.3) ---------------------------------------------
+
+/**
+ * A capability advertised by a node — physical hardware (NICs, GPUs,
+ * capture cards), installed software (drivers, licenses), or capabilities
+ * provided dynamically by a NodeService. Stringly-typed namespaced names
+ * follow the K8s extended-resource pattern; see `KnownCapabilities` for
+ * the standard names shipped with Norsk.
+ *
+ * @public
+ */
+export interface Capability {
+  /** Namespaced name, e.g. "norsk.io/st2110-nic", "acme/license-key". */
+  name: string;
+  /** Integer count, exclusive in v1. */
+  count: number;
+  /** Optional metadata used for matching and runtime service-discovery. */
+  attributes?: Record<string, string>;
+}
+
+/**
+ * A capability a job requires. Matches against a node's advertised
+ * capabilities by name and (optionally) by attribute equality.
+ *
+ * @public
+ */
+export interface CapabilityRequirement {
+  name: string;
+  count: number;
+  /**
+   * Each entry must be present on the matched capability with the given
+   * value. Useful for "GPU model = RTX 4090" or "license tier = enterprise".
+   */
+  attributeMatches?: Record<string, string>;
+}
+
+// ----- Priority bands (§3.4) -------------------------------------------
+
+/** @public */
+export type PriorityBand = "gold" | "silver" | "bronze";
+
+// ----- Job requirements ------------------------------------------------
+
+/**
+ * Resource and policy requirements for a single job. Bundles of jobs
+ * compose these per-job specs together; placement filters and scoring
+ * use them as inputs.
+ *
+ * @public
+ */
+export interface JobRequirements {
+  requiredCapacity: Capacity;
+  /** Omit (or 0) to share whatever cores are available — no cpuset pin. */
+  requiredCores?: CoreCount;
+  /** GPU reference units. Omit if the job doesn't need a GPU. */
+  requiredGpuCapacity?: number;
+  /** Optional model match (e.g. "RTX 4090") for the chosen GPU. */
+  requiredGpuModel?: string;
+  /** Counted/exclusive resources — hardware and software capabilities. */
+  requiredCapabilities: CapabilityRequirement[];
+  priorityBand: PriorityBand;
+}
+
+// ----- Bundles & replicas (§3.5) ---------------------------------------
+
+/**
+ * A bundle is a logical workload unit. It runs a primary copy plus — when
+ * a `resiliencePolicy` is set — one backup (replica index 0 = primary,
+ * 1 = backup). The copy count is derived, not operator-set (see
+ * `replicaCount`). Each copy's jobs are placed under the bundle's
+ * intra-replica rules; the primary is placed against the bundle's single
+ * `pool` (cost cascade lives in the pool's ordered tiers), the backup from
+ * the resilience policy's pool subject to its anti-affinity flags.
+ *
+ * @public
+ */
+export interface Bundle {
+  bundleId: BundleId;
+  /** The pool this bundle's primary jobs are placed into. */
+  pool: string;
+  jobs: BundleJobSpec[];
+  intraReplicaPlacement?: IntraReplicaRules;
+  /**
+   * When set, the bundle runs a primary + one backup; absent ⇒ active-only
+   * (primary only — AutoManager still restarts a failed primary).
+   */
+  resiliencePolicy?: ResiliencePolicy;
+  /**
+   * Lifecycle state. `"live"` for newly created bundles; transitions to
+   * `"deleting"` when an operator issues DeleteBundle and the daemon
+   * starts the stop-then-delete saga. The entry leaves the daemon's
+   * BundleStore once all jobs have confirmed stop. Optional on read so
+   * older callers can ignore the field; conversions default to `"live"`.
+   */
+  state?: BundleState;
+}
+
+/** @public */
+export type BundleState = "live" | "deleting";
+
+/** @public */
+export interface BundleJobSpec {
+  /** Unique within the bundle. */
+  jobName: string;
+  requirements: JobRequirements;
+  /** jobNames in the same replica that MUST land on the same node. */
+  coLocateWith?: string[];
+  /** jobNames in the same replica that MUST land on different nodes. */
+  separateFrom?: string[];
+  /**
+   * What this bundle member launches. Either a product-template tar (the new,
+   * preferred path; opaque to Manager, materialised by the worker's
+   * runner) or a legacy services/volumes Job template (existing
+   * pre-product-template flow).
+   *
+   * Per-replica differences flow through `Job.tags` projected into
+   * the product-template's `.env` by the worker — there is no separate
+   * per-replica parameter overlay. See
+   * `.ai/steve/tasks/39-blueprint-jobs.md`.
+   */
+  launch?: LaunchSpec;
+}
+
+/** @public */
+export type LaunchSpec =
+  | {
+      kind: "productTemplate";
+      ref: ProductTemplateRef;
+      /** Resolved env-var overrides for the compose stack (same for every replica). */
+      parameters?: Record<string, string>;
+      /**
+       * When this job should start. Required by Manager-daemon for every
+       * stored job; if omitted, AutoManager stamps `new Date()` (immediate)
+       * at conversion time. Surfaced explicitly so launch UIs can offer a
+       * "now / pick a future time" picker without needing a separate field.
+       */
+      startDateTime?: Date;
+      /**
+       * Optional auto-stop. When set and in the future, AutoManager
+       * schedules a per-bundle timer that fires `deleteBundle(bundleId)`
+       * at this instant. There's no daemon-side concept of stop time —
+       * this is wire-encoded as a reserved `__stopDateTime` tag on the
+       * proto Job (in `tags`), so it persists across reconnects via
+       * the daemon's tag store. Use `setBundleStopTime` to change after
+       * launch; the timer reschedules.
+       */
+      stopDateTime?: Date;
+      /**
+       * Free-form tags forwarded to PbJob.tags. Daemon preserves them
+       * verbatim; worker reads via cluster events. Names starting with
+       * `__` are reserved for SDK use (e.g. `__stopDateTime`) and are
+       * stripped on both inbound and outbound conversion — callers
+       * who try to set them get a quiet no-op.
+       */
+      tags?: Record<string, string>;
+    }
+  | {
+      kind: "legacy";
+      /** Job template Manager stamps per replica (legacy services/volumes path). */
+      job: ManagerSdk.Job;
+    };
+
+/** @public */
+export interface IntraReplicaRules {
+  /** Default sameNode for jobs without coLocateWith/separateFrom override. */
+  sameNodeDefault: boolean;
+  sameAz: "hard" | "soft" | "off";
+}
+
+/**
+ * Anti-affinity strength for a resilience-policy flag. v1 is best-effort
+ * always: `"forbid"` means "keep the backup out of this failure domain if
+ * at all possible" — but if no domain-respecting node is free the engine
+ * places it anyway and surfaces the degradation. `"allow"` = no constraint.
+ *
+ * @public
+ */
+export type AntiAffinity = "allow" | "forbid";
+
+/**
+ * When present on a bundle, the bundle runs a primary + one backup. The
+ * backup is placed from `pool` (omitted ⇒ the bundle's own pool) subject to
+ * the anti-affinity flags, which keep it in a different failure domain
+ * (node / AZ / cloud) from the primary.
+ *
+ * @public
+ */
+export interface ResiliencePolicy {
+  /** Backup capacity pool. Omitted ⇒ use the bundle's own `pool`. */
+  pool?: string;
+  sameNode: AntiAffinity;
+  sameAz: AntiAffinity;
+  sameCloud: AntiAffinity;
+}
+
+/**
+ * Derived copy count: primary (1) plus one backup when a resilience policy
+ * is present. Replaces the old operator-set `replicas` field.
+ *
+ * @public
+ */
+export function replicaCount(bundle: Bundle): number {
+  return bundle.resiliencePolicy ? 2 : 1;
+}
+
+// ----- Inventory (§3.6) ------------------------------------------------
+
+/**
+ * What a node advertises through `nodeInventoryUpdated` events. Workers
+ * are the source of truth — placement reads, never writes, this view.
+ *
+ * @public
+ */
+export interface NodeInventory {
+  totalCapacity: Capacity;
+  /** Fraction (0-1) of totalCapacity that's safe to allocate. */
+  utilizationCap: number;
+  totalCores: CoreCount;
+  gpus: GpuResource[];
+  capabilities: Capability[];
+  reservedCapacity: Capacity;
+  reservedCores: CoreCount;
+  reservedCapabilities: Capability[];
+  reachable: boolean;
+  lastSeen: Date;
+  /** Set true by an operator drain; placement skips this node. */
+  cordoned: boolean;
+  assignedJobs: NodeAssignedJob[];
+}
+
+/** @public */
+export interface NodeAssignedJob {
+  jobId: JobId;
+  /** CPU core indices, if pinned. */
+  coreSet?: number[];
+  /** Index of the GPU bound to this job, if any. */
+  gpuIndex?: number;
+}
+
+// ----- NodeService (§3.8) ----------------------------------------------
+
+/**
+ * A long-running job that consumes capabilities and provides new ones.
+ *
+ * The motivating example is an MXL bridge that takes exclusive
+ * possession of an ST2110 NIC (a `consumes` capability) and
+ * advertises N consumer slots (a `provides` capability) for other
+ * jobs on the same node to use.
+ *
+ * AutoManager's NodeService reconciler places services on every
+ * eligible node (for `lifecycle: "eager"`) or on first consumer
+ * demand (for `lifecycle: "lazy"` — deferred in v1).
+ *
+ * The actual capability advertisement is worker-side work
+ * (`provides[]` is added to the node's inventory by the worker once
+ * the service reaches `ready`). Without that, AutoManager places
+ * the service but no consumer can see its capabilities. See
+ * §"Worker-side work" in the design doc.
+ *
+ * @public
+ */
+export interface NodeService {
+  serviceId: ServiceId;
+  /**
+   * SDK-shape runtime Job template. AutoManager stamps in the
+   * generated jobId and adds `tags["nodeService"] = serviceId` and
+   * `tags["auto-manager"] = "true"`; everything else flows through
+   * verbatim. The worker recognises NodeService instances by the
+   * `nodeService` tag.
+   */
+  jobSpec: ManagerSdk.Job;
+  /** Capabilities the service requires from the host node. */
+  consumes: CapabilityRequirement[];
+  /** Capabilities the service advertises while running and ready. */
+  provides: Capability[];
+  /** Pool names the reconciler considers when placing this service. */
+  pools: string[];
+  /**
+   * - `eager`: place on every node in `pools` that satisfies `consumes`.
+   * - `lazy`: place only when an unplaceable consumer would benefit.
+   *   (Deferred in v1 — only eager is implemented.)
+   */
+  lifecycle: "eager" | "lazy";
+}
+
+// ----- Re-export IDs we reuse from manager-sdk -------------------------
+
+export type { JobId, NodeId, Role };

package/src/validation.ts

@@ -0,0 +1,297 @@
+// Static validation of Bundle definitions at submission time. Per §4.3
+// of the design doc, this catches constraint contradictions and "no
+// allowed pool can ever satisfy this" cases before placement runs.
+//
+// Two flavours of result:
+//   • `errors`   — spec is structurally wrong; submission must be
+//                  rejected (unknown pool, duplicate job name, contradictory
+//                  placement, capacity unsatisfiable in an elastic pool
+//                  with a fixed candidateInstanceTypes list, etc).
+//   • `warnings` — spec is structurally fine but current capacity won't
+//                  satisfy it. Specifically the `unsatisfiable*`
+//                  conditions when ANY targeted pool is `kind: "cluster"`
+//                  — those pools' capacity is event-driven (workers can
+//                  join later), so a snapshot-time miss isn't a permanent
+//                  reject. Callers should surface warnings to the operator
+//                  but still allow submission; placement will queue or
+//                  fail at runtime as appropriate.
+//
+// The function is pure: callers pass in the bundle and a description of
+// the configured pools; it returns ValidationResult.
+
+import { Bundle, Capability, CapabilityRequirement, Capacity, CoreCount } from "./types";
+
+/** @public */
+export interface ValidationError {
+  /** Stable machine-readable code for tests / structured logging. */
+  code: ValidationErrorCode;
+  /** Human-readable message including the offending value. */
+  message: string;
+}
+
+/** @public */
+export type ValidationErrorCode =
+  | "duplicateJobName"
+  | "unknownJobNameInPlacement"
+  | "selfReferenceInPlacement"
+  | "contradictoryPlacement"
+  | "unsatisfiableCapacity"
+  | "unsatisfiableCores"
+  | "unsatisfiableCapability"
+  | "emptyPoolList"
+  | "unknownPoolName"
+  | "unknownResiliencePool"
+  | "resilienceUnsatisfiable";
+
+/**
+ * Outcome of validateBundle. An empty `errors` array means submission
+ * is allowed; `warnings` may still be non-empty (capacity issues against
+ * a cluster pool, where workers may join later).
+ *
+ * @public
+ */
+export interface ValidationResult {
+  errors: ValidationError[];
+  warnings: ValidationError[];
+}
+
+/**
+ * Description of a configured pool, sufficient for static validation. A
+ * pool's `nodeProfiles` represent the kinds of node available — for
+ * elastic pools this is each allowed instance type's capability set;
+ * for fixed cluster pools it's the actual registered nodes' capability
+ * sets. Validation accepts a bundle if at least one profile in at least
+ * one named pool can satisfy each requirement.
+ *
+ * `kind` controls whether an unsatisfied capacity / cores / capability
+ * requirement becomes a hard `error` ("elastic"; candidateInstanceTypes
+ * is operator-configured and time-invariant — if it doesn't fit, future
+ * instances won't either) or a soft `warning` ("cluster"; live worker
+ * inventory may change before placement runs).
+ *
+ * @public
+ */
+export interface PoolDescriptor {
+  poolName: string;
+  kind: "elastic" | "cluster";
+  nodeProfiles: NodeProfile[];
+  /** Distinct cloud/failure-domain keys the pool's tiers span (tier kinds).
+   *  Used for the resilience sameCloud cardinality check. */
+  clouds: string[];
+}
+
+/** @public */
+export interface NodeProfile {
+  /**
+   * Reference-workload-normalised compute score the node advertises
+   * (or, for elastic pools, what the candidate instance type is
+   * scored at). Used to statically reject bundles whose
+   * `requiredCapacity` exceeds the largest profile available in any
+   * candidate pool.
+   */
+  totalCapacity: Capacity;
+  totalCores: CoreCount;
+  capabilities: Capability[];
+}
+
+/**
+ * Validate a Bundle against a set of configured pools. Returns all
+ * findings (does not short-circuit on first one) so callers can surface
+ * a complete list to the user. See `ValidationResult` for the
+ * errors-vs-warnings split.
+ *
+ * @public
+ */
+export function validateBundle(
+  bundle: Bundle,
+  pools: PoolDescriptor[]
+): ValidationResult {
+  const errors: ValidationError[] = [];
+  const warnings: ValidationError[] = [];
+  const knownPools = new Set(pools.map((p) => p.poolName));
+
+  // ---- pool ----
+  if (bundle.pool.length === 0) {
+    errors.push({
+      code: "emptyPoolList",
+      message: "bundle.pool must name a pool",
+    });
+  } else if (!knownPools.has(bundle.pool)) {
+    errors.push({
+      code: "unknownPoolName",
+      message: `pool "${bundle.pool}" is not configured`,
+    });
+  }
+
+  // ---- resilience policy ----
+  // Static reject is cardinality-only: the clearly-impossible case where the
+  // backup shares the primary's pool and that pool spans a single cloud, so
+  // sameCloud:forbid can never be honoured. AZ/node spans aren't statically
+  // known (cluster nodes register, elastic AZs are region-dependent), so
+  // those flags are best-effort at runtime, not rejected here.
+  const policy = bundle.resiliencePolicy;
+  if (policy) {
+    if (policy.pool !== undefined && !knownPools.has(policy.pool)) {
+      errors.push({
+        code: "unknownResiliencePool",
+        message: `resiliencePolicy.pool "${policy.pool}" is not configured`,
+      });
+    }
+    if (policy.sameCloud === "forbid") {
+      const samePool = policy.pool === undefined || policy.pool === bundle.pool;
+      const primaryPool = pools.find((p) => p.poolName === bundle.pool);
+      if (samePool && primaryPool && primaryPool.clouds.length < 2) {
+        errors.push({
+          code: "resilienceUnsatisfiable",
+          message: `resiliencePolicy sameCloud:forbid, but the backup shares pool "${bundle.pool}" which spans a single cloud`,
+        });
+      }
+    }
+  }
+
+  // ---- jobs ----
+  const jobNames = new Set<string>();
+  const seenNames = new Set<string>();
+  for (const j of bundle.jobs) {
+    if (seenNames.has(j.jobName)) {
+      errors.push({
+        code: "duplicateJobName",
+        message: `duplicate jobName "${j.jobName}" in bundle`,
+      });
+    }
+    seenNames.add(j.jobName);
+    jobNames.add(j.jobName);
+  }
+
+  // Need a complete name set before checking cross-references.
+  for (const j of bundle.jobs) {
+    const coLocate = new Set(j.coLocateWith ?? []);
+    const separate = new Set(j.separateFrom ?? []);
+
+    for (const ref of coLocate) {
+      if (ref === j.jobName) {
+        errors.push({
+          code: "selfReferenceInPlacement",
+          message: `job "${j.jobName}" coLocateWith references itself`,
+        });
+      } else if (!jobNames.has(ref)) {
+        errors.push({
+          code: "unknownJobNameInPlacement",
+          message: `job "${j.jobName}" coLocateWith references unknown jobName "${ref}"`,
+        });
+      }
+    }
+    for (const ref of separate) {
+      if (ref === j.jobName) {
+        errors.push({
+          code: "selfReferenceInPlacement",
+          message: `job "${j.jobName}" separateFrom references itself`,
+        });
+      } else if (!jobNames.has(ref)) {
+        errors.push({
+          code: "unknownJobNameInPlacement",
+          message: `job "${j.jobName}" separateFrom references unknown jobName "${ref}"`,
+        });
+      }
+    }
+    for (const ref of coLocate) {
+      if (separate.has(ref)) {
+        errors.push({
+          code: "contradictoryPlacement",
+          message: `job "${j.jobName}" both coLocateWith and separateFrom "${ref}"`,
+        });
+      }
+    }
+
+    // ---- requirement vs. pool capacity ----
+    const requestedPools = poolsForJob(bundle, knownPools);
+    if (requestedPools.length > 0) {
+      const reqs = j.requirements;
+      // Whether the job's pool list includes any cluster-kind pool
+      // determines whether unsatisfiable* outcomes are errors (no
+      // cluster pool — only elastic pools whose candidateInstanceTypes
+      // is operator-configured, so a miss is permanent) or warnings
+      // (cluster pool present — capacity can arrive via a worker
+      // joining; let the operator submit anyway).
+      const targetsCluster = requestedPools.some((name) => {
+        const pool = pools.find((p) => p.poolName === name);
+        return pool?.kind === "cluster";
+      });
+      const pushUnsatisfiable = (entry: ValidationError) =>
+        (targetsCluster ? warnings : errors).push(entry);
+
+      if (reqs.requiredCapacity > 0) {
+        if (
+          !anyProfileSatisfies(requestedPools, pools, (prof) =>
+            prof.totalCapacity >= reqs.requiredCapacity
+          )
+        ) {
+          pushUnsatisfiable({
+            code: "unsatisfiableCapacity",
+            message: `job "${j.jobName}" requires capacity ${reqs.requiredCapacity}, no node profile in any allowed pool offers it`,
+          });
+        }
+      }
+      if (reqs.requiredCores !== undefined && reqs.requiredCores > 0) {
+        if (
+          !anyProfileSatisfies(requestedPools, pools, (prof) =>
+            prof.totalCores >= (reqs.requiredCores ?? 0)
+          )
+        ) {
+          pushUnsatisfiable({
+            code: "unsatisfiableCores",
+            message: `job "${j.jobName}" requires ${reqs.requiredCores} cores, no node profile in any allowed pool meets this`,
+          });
+        }
+      }
+      for (const cap of reqs.requiredCapabilities) {
+        if (
+          !anyProfileSatisfies(requestedPools, pools, (prof) =>
+            profileSatisfiesCapability(prof, cap)
+          )
+        ) {
+          pushUnsatisfiable({
+            code: "unsatisfiableCapability",
+            message: `job "${j.jobName}" requires capability "${cap.name}" count ${cap.count}, no node profile in any allowed pool advertises it`,
+          });
+        }
+      }
+    }
+  }
+
+  return { errors, warnings };
+}
+
+function poolsForJob(bundle: Bundle, knownPools: Set<string>): string[] {
+  // Which pool might a job land in? Just the bundle's single pool (if it's
+  // configured). If it can satisfy the requirement we don't report it as
+  // statically unsatisfiable.
+  return knownPools.has(bundle.pool) ? [bundle.pool] : [];
+}
+
+function anyProfileSatisfies(
+  poolNames: string[],
+  pools: PoolDescriptor[],
+  pred: (p: NodeProfile) => boolean
+): boolean {
+  for (const name of poolNames) {
+    const pool = pools.find((p) => p.poolName === name);
+    if (!pool) continue;
+    if (pool.nodeProfiles.some(pred)) return true;
+  }
+  return false;
+}
+
+function profileSatisfiesCapability(
+  profile: NodeProfile,
+  req: CapabilityRequirement
+): boolean {
+  const cap = profile.capabilities.find((c) => c.name === req.name);
+  if (!cap || cap.count < req.count) return false;
+  if (req.attributeMatches) {
+    for (const [k, v] of Object.entries(req.attributeMatches)) {
+      if (cap.attributes?.[k] !== v) return false;
+    }
+  }
+  return true;
+}

package/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "allowJs": true,
+    "composite": true,
+    "declaration": true,
+    "declarationMap": true,
+    "esModuleInterop": true,
+    "experimentalDecorators": true,
+    "module": "commonjs",
+    "noImplicitAny": true,
+    "outDir": "lib",
+    "sourceMap": true,
+    "sourceRoot": "src",
+    "strictFunctionTypes": true,
+    "strictNullChecks": true,
+    "stripInternal": true,
+    "strictPropertyInitialization": false,
+    "target": "ES2020",
+    "typeRoots": ["./node_modules/@types", "../../node_modules/@types"],
+    "types": ["node", "uuid"]
+  },
+  "include": [
+    "./src/**/*"
+  ]
+}