@norskvideo/norsk-auto-manager 0.1.0

package/lib/src/automanager.d.ts

@@ -0,0 +1,1070 @@
+import * as ManagerPB from "@norskvideo/norsk-api/lib/manager_pb";
+import { Clock } from "./clock";
+import { Bundle as TypedBundle, BundleId, NodeInventory as TypedNodeInventory, NodeService, PriorityBand, ServiceId } from "./types";
+import { ValidationError, ValidationResult } from "./validation";
+import { PlacementFailureReason, PlacementPool, PlacementResult, PlacementTrace, ResilienceFlag } from "./placement";
+import { NorskManager, JobId, JobInfo, JobWithHistory, NodeId, NodeMetadata, Role, RunningNodeMetadata } from "@norskvideo/norsk-manager-sdk";
+import type * as ManagerSdk from "@norskvideo/norsk-manager-sdk";
+export type NodeState = "starting" | "running" | "stopping" | "stopped" | "terminating" | "terminated";
+export type NodeSummary = {
+    nodeId: NodeId;
+    nodeMetadata?: NodeMetadata;
+    runningNodeMetadata?: RunningNodeMetadata;
+    nodeState: NodeState;
+    lastActivity: Date;
+    provisional?: {
+        jobId: JobId;
+        role: Role;
+    };
+};
+export interface AutoSettings {
+    url?: string;
+    /**
+     * Abort the connection / run. Aborting before `run()` connects rejects it
+     * (so a connect-with-timeout retry loop can give up cleanly without
+     * leaving an abandoned SDK connection alive); aborting a running
+     * AutoManager tears down its Manager connection, ending the run loop.
+     */
+    signal?: AbortSignal;
+    /** Seconds-from-now window for jobs to be considered pending in the eventStream. */
+    pendingWindow: number;
+    /** Seconds stopped nodes persist before being terminated. */
+    removeStoppedNodesAfter: number;
+    /** Configured pools; a bundle names one, placement walks its tiers. */
+    placementPools: PlacementPool[];
+    /**
+     * Window (ms) for counting jobRejected events per-node. Default 5_000.
+     * Once `rejectionEscalationCount` rejections fall inside this window the
+     * node is marked "unhealthy" and excluded from placement until the next
+     * `nodeInventoryUpdated` event clears the mark.
+     */
+    rejectionBackoffMs?: number;
+    /** Default 3. */
+    rejectionEscalationCount?: number;
+    /**
+     * After a node fails (`nodeStopping`), how long to keep it excluded from
+     * placement. Default 30_000 ms. Cleared by a subsequent
+     * `nodeInventoryUpdated` event reporting the node as reachable again.
+     */
+    failureBackoffMs?: number;
+    /**
+     * Phase C2: per-replica restart-rate ceiling on the recovery path.
+     * When a replica's restart count in the trailing hour exceeds this,
+     * AutoManager stops re-placing it (and every other replica of the
+     * same bundle), marks the bundle broken, and fires `onBundleBroken`.
+     * Cleared when the bundle is updated or deleted, or when a fresh
+     * `jobUpdated` arrives for the broken job. Default 6 (per design).
+     */
+    maxRestartsPerHour?: number;
+    /**
+     * Phase C3: node startup grace. If a node stays in `nodeStarting`
+     * for longer than this, AutoManager terminates it — Manager emits a
+     * `nodeStopping` and the existing band-aware recovery path replaces
+     * the job. Default 120_000 ms.
+     *
+     * (In v1, "job in starting" and "node in starting" collapse onto
+     * the same signal because `running → ready` is auto-marked. The
+     * design's distinction matters when explicit readiness lands.)
+     */
+    jobStartupGraceMs?: number;
+    /**
+     * Phase C4 — per-band recovery policy. When set, takes precedence
+     * over the flat fields above. Bronze always drops (`onFailure:
+     * "drop"`) — no per-band restart options. Gold and silver get
+     * their own `maxRestartsPerHour`; gold additionally has
+     * `restartPlacement: "preferHotSpare"` baked in by the recovery
+     * path. Omitted bands fall back to the flat top-level fields, then
+     * to defaults.
+     */
+    bands?: BandConfig;
+    /**
+     * Phase C4 — placement / recovery tunables grouped into one typed
+     * object. Same precedence as `bands`: object field beats flat field
+     * beats default. The flat fields above are preserved for one
+     * release; new code should prefer this shape.
+     */
+    placement?: PlacementConfig;
+    /**
+     * Phase C6 — hot-spare reconciliation configuration. One entry per
+     * (pool, optional band). The reconciler runs on node lifecycle
+     * events and on a periodic tick: counts live spares per entry,
+     * provisions short, terminates excess. Empty/omitted = no spares.
+     */
+    hotSpares?: HotSpareConfig[];
+    /**
+     * Phase F — NodeService configurations. Each entry describes a
+     * long-running service that consumes capabilities (typically
+     * exclusive hardware) and advertises new ones for sibling jobs
+     * to consume. AutoManager's reconciler places eager services on
+     * every eligible node and tears them down when a node loses
+     * eligibility.
+     *
+     * Worker-side capability advertisement is required for sibling
+     * jobs to actually see the provided capabilities — see
+     * `§Worker-side work` in the design doc.
+     */
+    nodeServices?: NodeService[];
+    /**
+     * Phase F — how often the NodeService reconciler's periodic tick
+     * fires. Event-driven reconciles handle most cases; the tick is a
+     * safety net. Default 60_000 ms.
+     */
+    nodeServiceReconcileIntervalMs?: number;
+    /**
+     * Phase C6 — how often the spare reconciler's periodic tick fires.
+     * Event-driven reconciles handle most cases; the tick is a safety
+     * net for missed signals. Default 60_000 ms.
+     */
+    hotSpareReconcileIntervalMs?: number;
+    /**
+     * Phase E — per-phase deadline configuration for in-flight
+     * migrations. If a migration sits in a phase longer than the
+     * configured window, AutoManager auto-aborts with reason
+     * `phase timeout: <phase>`. Operators can still abort manually via
+     * `abortMigration` before the deadline fires.
+     */
+    migration?: MigrationConfig;
+    onError?: (err: unknown) => void;
+    onNodeStarting?: (node: NodeId) => void;
+    onNodeStarted?: (node: NodeSummary) => void;
+    /** Fired when the daemon emits a NodeStopping event — the node is
+     *  going away but may not have fully terminated yet. For cluster
+     *  workers Ctrl-C'd at the keyboard this is the signal that fires
+     *  (NodeStopped/NodeTerminated come later, after the daemon's
+     *  keepalive timeout or cleanup loop). Consumers wanting prompt
+     *  "worker dropped" UI updates listen here. */
+    onNodeStopping?: (nodeId: NodeId) => void;
+    onNodeStopped?: (nodeId: NodeId) => void;
+    onNodeTerminated?: (nodeId: NodeId) => void;
+    onBundleUpdated?: (bundle: TypedBundle) => void;
+    onBundleDeleted?: (bundleId: BundleId) => void;
+    /**
+     * Fired when the daemon appends a new audit-log entry (any source).
+     * Pure pass-through of the SDK's `AuditLogEntry` — AutoManager doesn't
+     * own audit semantics, it just forwards the live append so consumers
+     * can tail the log without re-polling GetAuditLog.
+     */
+    onAuditAppended?: (entry: ManagerSdk.AuditLogEntry) => void;
+    /**
+     * Fires when a node accumulates enough rejections within
+     * `rejectionBackoffMs` to be marked unhealthy. Operators may want to
+     * surface this in monitoring.
+     */
+    onNodeUnhealthy?: (nodeId: NodeId) => void;
+    /**
+     * Fired after `jobMap` is updated in response to a `jobUpdated` or
+     * `jobPending` event. Carries the full `JobWithHistory` so consumers
+     * can render state transitions without a separate SDK round-trip.
+     */
+    onJobUpdated?: (jobWithHistory: JobWithHistory) => void;
+    /**
+     * Fired for an informational job message from the worker — launch
+     * progress (pulling-images / starting-containers / health), container
+     * events, service lifecycle. Lets consumers surface live launch feedback
+     * tied to a job without changing its placement state.
+     */
+    onJobInfo?: (info: JobInfo) => void;
+    /**
+     * Fired after a job is removed from `jobMap` in response to a
+     * `jobDeleted` or `jobOutOfWindow` event.
+     */
+    onJobDeleted?: (jobId: JobId) => void;
+    /**
+     * Fired on every `jobRejected` event after AutoManager has updated
+     * its inventory cache. Note the node is not necessarily marked
+     * unhealthy by this single occurrence — see `onNodeUnhealthy` for
+     * escalation.
+     */
+    onJobRejected?: (info: JobRejectedInfo) => void;
+    /**
+     * Fired on `jobConfigUpdated` after AutoManager has updated its
+     * mirror of the job's `managerConfiguration`.
+     */
+    onJobConfigUpdated?: (jobId: JobId, config: string) => void;
+    /**
+     * Fires every time the placement engine runs, regardless of outcome.
+     * Carries the full trace so consumers (e.g. an operator UI) can show
+     * "why did my job land here?" without re-running placement
+     * themselves.
+     */
+    onPlacementDecision?: (info: PlacementDecisionInfo) => void;
+    /**
+     * Fires when the placement engine returns `kind: "failure"`. Today
+     * the failure also surfaces via `onError` as a stringified message;
+     * this typed callback is the recommended path. The two are not
+     * mutually exclusive — `onError` is preserved for back-compat.
+     */
+    onPlacementFailed?: (info: PlacementFailedInfo) => void;
+    /**
+     * Fired whenever the underlying gRPC channel changes connectivity
+     * state. Maps the five gRPC connectivity states to the strings
+     * `idle | connecting | ready | transientFailure | shutdown`.
+     * Lets a consumer surface "connected / reconnecting / disconnected"
+     * without holding a separate NorskManager handle.
+     */
+    onConnectionStateChange?: (state: ConnectionState) => void;
+    /**
+     * Phase-C: fired when a bundle's restart rate exceeds the band's
+     * `maxRestartsPerHour` and AutoManager marks it broken. Declared
+     * now so consumers can wire the callback; not fired in pre-Phase-C
+     * code.
+     */
+    onBundleBroken?: (bundleId: BundleId, reason: string) => void;
+    /**
+     * Phase-C: fired when a bronze-band job fails and is dropped
+     * (rather than restarted). Declared now; not fired in pre-Phase-C
+     * code.
+     */
+    onJobDropped?: (jobId: JobId) => void;
+    /**
+     * Phase-C: fired when a hot-spare pool's live spare count is below
+     * its configured target. Declared now; not fired in pre-Phase-C
+     * code.
+     */
+    onSpareUnderflow?: (pool: string, current: number, target: number) => void;
+    /**
+     * Fired when a bundle's backup is best-effort placed inside a failure
+     * domain its resilience policy asked to avoid (no compliant node had
+     * capacity). The backup is running, but DR posture is reduced — surface
+     * it so an operator can act / re-place when capacity frees.
+     */
+    onResilienceDegraded?: (info: ResilienceDegradedInfo) => void;
+    /**
+     * Phase E — fired on every migration phase transition. Use for
+     * telemetry / ops UIs. The payload is the post-transition state;
+     * `phaseHistory[0]` is launch, `phaseHistory.at(-1)` is the current
+     * phase at the time of the callback.
+     */
+    onMigrationPhase?: (info: MigrationState) => void;
+    /** Phase E — fired once when a migration reaches `done`. */
+    onMigrationCompleted?: (migrationId: MigrationId) => void;
+    /** Phase E — fired once when a migration enters `aborted`. */
+    onMigrationAborted?: (migrationId: MigrationId, reason: string) => void;
+    /** Optional clock injection. Production unset (RealClock); tests pass MockClock. */
+    clock?: Clock;
+}
+/** Fixed role for the migration-target instance. No concurrent migrations per Job. @public */
+export declare const MIGRATION_TARGET_ROLE = "migrationTarget";
+/**
+ * Fixed role assigned to runtime jobs that exist to back a
+ * NodeService. Worker reads `WorkerJob.role === NODE_SERVICE_ROLE`
+ * to recognise the instance as a service rather than a regular
+ * workload, and adds the service's `provides[]` capabilities to its
+ * inventory once the job reaches `ready`.
+ *
+ * @public
+ */
+export declare const NODE_SERVICE_ROLE = "nodeService";
+/** @public */
+export type MigrationId = string;
+/** @public */
+export type MigrationPhase = "launching" | "awaitingTargetReady" | "awaitingSourceStop" | "applying" | "done" | "aborted";
+/**
+ * Phase E migration state, kept entirely in AutoManager. Per the
+ * design, "no concurrent migrations per Job" — `sourceJobId` is the
+ * primary index; `migrationId` is a stable opaque handle for ops
+ * tooling.
+ *
+ * @public
+ */
+export interface MigrationState {
+    migrationId: MigrationId;
+    sourceJobId: JobId;
+    sourceRole: Role;
+    targetNodeId: NodeId;
+    startedAt: Date;
+    phase: MigrationPhase;
+    phaseHistory: {
+        phase: MigrationPhase;
+        at: Date;
+    }[];
+    /** Set when phase becomes "aborted"; undefined while in flight or on done. */
+    abortReason?: string;
+    /** Timestamp the source reported as its last-output, captured during cutover. */
+    cutoverTimestampNs?: number;
+}
+/**
+ * Coarse connection state surfaced by `onConnectionStateChange`. Maps
+ * to gRPC's `ChannelConnectivityState` values via NorskManager's
+ * existing watcher.
+ *
+ * @public
+ */
+export type ConnectionState = "idle" | "connecting" | "ready" | "transientFailure" | "shutdown";
+/**
+ * Phase C4 — per-band recovery policy. Bronze always drops on
+ * failure; gold and silver restart with their own restart-rate
+ * ceilings. Gold's `restartPlacement: "preferHotSpare"` is the
+ * default behaviour of the recovery path (placement engine biases
+ * scoring toward spare-tagged nodes when the recovering job is gold).
+ *
+ * Omitted bands fall through to the flat `AutoSettings` fields, then
+ * to compiled-in defaults.
+ *
+ * @public
+ */
+export interface BandConfig {
+    gold?: {
+        onFailure: "restart";
+        restartPlacement: "preferHotSpare" | "any";
+        /** Default: 6 */
+        maxRestartsPerHour?: number;
+    };
+    silver?: {
+        onFailure: "restart";
+        restartPlacement: "any";
+        /** Default: 6 */
+        maxRestartsPerHour?: number;
+    };
+    bronze?: {
+        onFailure: "drop";
+    };
+}
+/**
+ * Phase C4 — placement / recovery tunables. Same fields as the flat
+ * top-level settings; this typed grouping is the recommended path.
+ * Omitted fields fall through to the flat settings, then to
+ * compiled-in defaults.
+ *
+ * @public
+ */
+export interface PlacementConfig {
+    /** Default: 5_000 ms. */
+    rejectionBackoffMs?: number;
+    /** Default: 3. */
+    rejectionEscalationCount?: number;
+    /** Default: 30_000 ms. */
+    failureBackoffMs?: number;
+    /** Default: 120_000 ms. */
+    jobStartupGraceMs?: number;
+}
+/**
+ * Phase C6 — keep `targetCount` warm-running nodes ready per pool
+ * (and optional band). The reconciler provisions short, terminates
+ * excess. Cluster pools cannot auto-scale — `targetCount` there
+ * means "refuse to place onto a spare-tagged node unless this is a
+ * recovery placement"; reconciler emits `onSpareUnderflow` and leaves
+ * the rest to operator IT.
+ *
+ * @public
+ */
+export interface HotSpareConfig {
+    pool: string;
+    targetCount: number;
+    /** Optional: dedicate spares to a specific band. */
+    forBand?: PriorityBand;
+    spec: NodeSpec;
+}
+/**
+ * Phase C6 — what kind of node the spare reconciler should
+ * provision. For elastic (aws/oci) pools, `instanceType` is
+ * required. For cluster pools, the spec is only used to constrain
+ * which existing cluster nodes are eligible to be tagged as spare
+ * (future).
+ *
+ * @public
+ */
+export interface NodeSpec {
+    /** AwsInstanceType | OciShape; required for elastic pools. */
+    instanceType?: string;
+    /** Cloud-specific region or AZ; pass through to provider. */
+    region?: string;
+    az?: string;
+}
+/**
+ * Phase E — per-phase deadlines for in-flight migrations. Set any
+ * field to override its default; omitted fields use the compiled-in
+ * default below.
+ *
+ * @public
+ */
+export interface MigrationConfig {
+    /** Default 120_000 ms — combined "launch + ready" window for the target. */
+    launchingDeadlineMs?: number;
+    /** Default 120_000 ms — workflow has this long after target running to signal ready. */
+    awaitingTargetReadyDeadlineMs?: number;
+    /** Default 30_000 ms — source workflow has this long to stop output after the cutover signal. */
+    awaitingSourceStopDeadlineMs?: number;
+    /** Default 10_000 ms — target workflow has this long to apply the handover. */
+    applyingDeadlineMs?: number;
+}
+/**
+ * Phase C4 — result of `validateBundleAdmission`. `ok` means the
+ * bundle passes static validation AND every (replica, jobName)
+ * placeDryRun would succeed at the current moment. The two failure
+ * modes are distinct: `validationErrors` is "the bundle spec itself
+ * is broken" (operator must fix); `noCapacity` is "current cluster
+ * state can't host this" (operator must add capacity or wait).
+ *
+ * @public
+ */
+export type AdmissionResult = {
+    kind: "ok";
+} | {
+    kind: "validationErrors";
+    errors: ValidationError[];
+} | {
+    kind: "noCapacity";
+    unplaceable: AdmissionUnplaceable[];
+};
+/** @public */
+export interface AdmissionUnplaceable {
+    replicaIndex: number;
+    jobName: string;
+    reason: PlacementFailureReason;
+}
+/**
+ * Phase D4 — operational metrics snapshot. Cumulative counters since
+ * `startedAt`; per-pool gauges are point-in-time at call. Consumers
+ * (telemetry pipelines, ops UIs) poll `AutoManager.metrics()` on
+ * their own cadence.
+ *
+ * @public
+ */
+export interface AutoManagerMetrics {
+    /** AutoManager.run() entry time; undefined before runInternal starts. */
+    startedAt?: Date;
+    /** Milliseconds since startedAt, 0 if not yet started. */
+    uptimeMs: number;
+    placementsAttempted: number;
+    /**
+     * Placement that successfully dispatched its wire call (startJob /
+     * createAwsNode / createOciNode). Counted post-RPC, so a successful
+     * decision whose dispatch then fails does not bump this counter —
+     * see `placementsDispatchFailed`.
+     */
+    placementsSucceeded: number;
+    /** Placement engine returned `failure` (no suitable target). */
+    placementsFailed: number;
+    /**
+     * Decision succeeded but the downstream RPC (startJob /
+     * createAwsNode / createOciNode) rejected. The job is left
+     * unplaced; AutoManager surfaces the error via onError.
+     */
+    placementsDispatchFailed: number;
+    jobsRejected: number;
+    bundlesBroken: number;
+    /** Bronze-band drops. */
+    jobsDropped: number;
+    pools: PoolMetrics[];
+    /** Bundles currently marked broken by the restart-rate ceiling. */
+    brokenBundleIds: BundleId[];
+}
+/** @public */
+export interface PoolMetrics {
+    poolName: string;
+    nodeCount: number;
+    /** Spare-tagged, running, no jobs assigned. */
+    liveSpares: number;
+    /** Sum of `targetCount` across hotSpares entries for this pool. */
+    spareTarget: number;
+    /**
+     * Mean reservedCapacity / totalCapacity across nodes with inventory.
+     * 0 if there are no nodes with inventory.
+     */
+    usedCapacityFraction: number;
+}
+/**
+ * Payload for `onPlacementDecision`. The `bundleId`/`replicaIndex`/
+ * `jobName` triple identifies which bundle member the decision was made
+ * for; `result` is the placement engine's verdict; `trace` is the
+ * per-pool filter/score breakdown described in §6 of the design.
+ *
+ * @public
+ */
+export interface PlacementDecisionInfo {
+    jobId: JobId;
+    bundleId: BundleId;
+    replicaIndex: number;
+    jobName: string;
+    result: PlacementResult;
+    trace: PlacementTrace;
+    at: Date;
+}
+/**
+ * Payload for `onPlacementFailed`. `triedPools` is the ordered list of
+ * tier names AutoManager attempted within the bundle's `pool` before
+ * giving up.
+ *
+ * @public
+ */
+export interface PlacementFailedInfo {
+    jobId: JobId;
+    bundleId: BundleId;
+    replicaIndex: number;
+    jobName: string;
+    reason: PlacementFailureReason;
+    triedPools: string[];
+    at: Date;
+}
+/**
+ * Payload for `onResilienceDegraded`. Fired when a bundle's backup
+ * (replicaIndex 1) is placed inside a failure domain its resilience policy
+ * asked to avoid, because no compliant node had capacity. `violated` lists
+ * the anti-affinity flags that couldn't be honoured. The placement still
+ * happened — a degraded backup beats no backup — but DR posture is reduced.
+ *
+ * @public
+ */
+export interface ResilienceDegradedInfo {
+    jobId: JobId;
+    bundleId: BundleId;
+    replicaIndex: number;
+    jobName: string;
+    violated: ResilienceFlag[];
+    /** Set when the primary is on interruptible (spot) capacity with no
+     *  durable backup — see ResilienceDegradation.interruptiblePrimary. */
+    interruptiblePrimary?: boolean;
+    at: Date;
+}
+/**
+ * Payload for `onJobRejected`. `inventory` is the typed snapshot the
+ * worker sent alongside the rejection so consumers can render "why" in
+ * the same UI tick as the rejection itself.
+ *
+ * @public
+ */
+export interface JobRejectedInfo {
+    jobId: JobId;
+    nodeId: NodeId;
+    reason: ManagerPB.JobRejected["reason"];
+    inventory?: TypedNodeInventory;
+    at: Date;
+}
+export declare class AutoManager {
+    norsk: NorskManager;
+    settings: AutoSettings;
+    clock: Clock;
+    jobMap: Map<JobId, JobWithHistory>;
+    nodeMap: Map<NodeId, NodeSummary>;
+    bundleMap: Map<BundleId, TypedBundle>;
+    inventoryMap: Map<NodeId, TypedNodeInventory>;
+    private rejectionsPerNode;
+    private unhealthyNodes;
+    private recentFailures;
+    private restartHistory;
+    private jobToNode;
+    private placementsByJob;
+    private pendingPlacementTimers;
+    private pendingStopTimers;
+    private pendingPlacementRetries;
+    private lastPlacementAttemptAt;
+    private brokenBundles;
+    private startupGraceTimers;
+    private pendingSpareProvisions;
+    private hotSpareReconcileInterval?;
+    private cordonedNodes;
+    private metricsCounters;
+    private migrationStates;
+    private migrationByJobId;
+    private migrationPhaseTimers;
+    private nodeServicePlacements;
+    private nodeServiceReconcileInterval?;
+    /**
+     * The moment `runInternal()` first entered (i.e. the eventStream was
+     * established). Undefined until then. Powers "AutoManager up for N
+     * minutes" affordances.
+     * @public
+     */
+    startedAt?: Date;
+    private cleanupInterval?;
+    private closed;
+    /** @public */
+    static run(settings: AutoSettings): Promise<[AutoManager, Promise<void>]>;
+    /** @public */
+    terminateNode(nodeId: NodeId): Promise<void>;
+    /**
+     * Phase C8 — cordon a node. AutoManager projects this onto every
+     * placement decision: cordoned nodes are filtered out, so no new
+     * placements land on them. Existing jobs continue running.
+     * Idempotent.
+     * @public
+     */
+    cordonNode(nodeId: NodeId): void;
+    /**
+     * Phase C8 — un-cordon a node, restoring it to the placement pool.
+     * Idempotent.
+     * @public
+     */
+    uncordonNode(nodeId: NodeId): void;
+    /**
+     * Phase C8 — whether a node is currently cordoned by AutoManager.
+     * @public
+     */
+    isCordoned(nodeId: NodeId): boolean;
+    /**
+     * Phase C8 — drain a node. Cordons it (so no new placements land
+     * here) and terminates the node — Manager emits `nodeStopping`
+     * for every job hosted there, and the existing band-aware recovery
+     * path re-places them onto other nodes (excluding this cordoned
+     * one). Bronze jobs are dropped; gold prefers hot spares.
+     *
+     * v1 takes the immediate-terminate path; the design's "graceful
+     * shuffle without recovery gap" needs Phase E job migration to
+     * land first.
+     * @public
+     */
+    drainNode(nodeId: NodeId): Promise<void>;
+    /**
+     * Shut down this AutoManager. Cancels periodic intervals and closes
+     * the underlying NorskManager — which causes the event-loop iterator
+     * to terminate, resolving the `Promise<void>` returned from `run()`.
+     * Idempotent.
+     * @public
+     */
+    close(): void;
+    /**
+     * Alias for `close()`. Provided for symmetry with the
+     * `using`-style disposal conventions emerging in TypeScript.
+     * @public
+     */
+    dispose(): void;
+    /**
+     * AutoManager v1 — submit a new bundle. The bundle is validated by
+     * Manager (per §4.3) and expanded into N replica jobs server-side;
+     * AutoManager mirrors the resulting state via the bundleUpdated +
+     * jobUpdated events. The returned bundleId matches the one Manager
+     * assigns (typically the same as bundle.bundleId, but Manager has
+     * the final word).
+     *
+     * @public
+     */
+    createBundle(bundle: TypedBundle): Promise<BundleId>;
+    /**
+     * AutoManager v1 — update an existing bundle.
+     * @public
+     */
+    updateBundle(bundle: TypedBundle): Promise<void>;
+    /**
+     * AutoManager v1 — delete a bundle and all its replica jobs.
+     * @public
+     */
+    deleteBundle(bundleId: BundleId): Promise<void>;
+    /**
+     * AutoManager v1 — activate a dormant (start_mode = "manual") bundle
+     * job. Manager removes the dormant tag and re-emits jobUpdated;
+     * AutoManager's placement path picks the job up via the standard
+     * flow. See §10.2 of the design.
+     * @public
+     */
+    startBundleJob(bundleId: BundleId, replicaIndex: number, jobName: string): Promise<void>;
+    /**
+     * AutoManager v1 — deactivate a bundle job (tag-flip).
+     *
+     * Runtime termination of an in-flight workload and empty-node
+     * release with linger are pre-go-live work tracked as Phase E.5
+     * (§10.2.1). Until they land, calling stopBundleJob on an active
+     * job marks it dormant for future placement but does not stop the
+     * currently-running worker.
+     * @public
+     */
+    stopBundleJob(bundleId: BundleId, replicaIndex: number, jobName: string): Promise<void>;
+    /**
+     * AutoManager v1 — typed view of the jobs Manager has told us about.
+     * `JobWithHistory` carries the state-transition log for each job so
+     * consumers can render lifecycle timelines without a separate
+     * round-trip.
+     * @public
+     */
+    jobs(): JobWithHistory[];
+    nodes(): NodeSummary[];
+    /**
+     * AutoManager v1 — typed view of the bundle definitions Manager has
+     * told us about. Mirror only; AutoManager owns no durable state.
+     * @public
+     */
+    bundles(): TypedBundle[];
+    /**
+     * Phase D4 — snapshot of AutoManager's operational metrics.
+     * Cumulative counters since `startedAt`; per-pool gauges computed
+     * at call time. Cheap to call repeatedly — consumers poll on their
+     * own cadence and compute deltas if they want rates.
+     * @public
+     */
+    metrics(): AutoManagerMetrics;
+    private computePoolMetrics;
+    /**
+     * Look up a single bundle by id. Convenience over `bundles().find(...)`.
+     * @public
+     */
+    bundleById(bundleId: BundleId): TypedBundle | undefined;
+    /**
+     * Every job (with history) that belongs to a given bundle. Derived
+     * from `tags.bundleId` on the job entries in jobMap. Returns an empty
+     * array if the bundle is unknown or has no jobs.
+     * @public
+     */
+    jobsForBundle(bundleId: BundleId): JobWithHistory[];
+    /**
+     * The node the given job is currently placed on, or undefined if
+     * the job hasn't been placed (or has been deleted). Useful for
+     * operator UIs that render "job X is on node Y" and for proxy
+     * routers that need to know which worker hosts each job.
+     *
+     * O(1) lookup against the `jobToNode` index — set at placement
+     * time, deleted on jobDeleted, rebuilt from job history on R7
+     * reconnect. Works regardless of whether the node hosts one job
+     * (cloud, today) or many (cluster, or any future cloud N:1)
+     * because the assignment is recorded against the JOB rather than
+     * scanned out of NODE tags.
+     * @public
+     */
+    nodeForJob(jobId: JobId): NodeSummary | undefined;
+    /**
+     * Current placement of every job AutoManager has bound to a node,
+     * newest-first by decision timestamp. Mirrors `nodeForJob` but
+     * returns the full `PlacementDecisionInfo` (so consumers get the
+     * pool, trace, replicaIndex etc., not just the node) — and exposes
+     * it as queryable live state rather than only via the
+     * `onPlacementDecision` event stream.
+     *
+     * Hydrated jobs (placed in a previous AutoManager generation, picked
+     * up on R7 reconnect) get an entry with an empty `trace.attempts`
+     * and a decision inferred from job history. Consumers that *need*
+     * a real trace should subscribe to `onPlacementDecision` for live
+     * decisions; this getter is for "where is everything right now?"
+     * operator views.
+     *
+     * @public
+     */
+    placements(): PlacementDecisionInfo[];
+    /**
+     * O(1) lookup for the most recent placement decision binding `jobId`
+     * to a node. Returns undefined for jobs that have never been placed
+     * (or whose placement attempts have only failed). @public
+     */
+    placementForJob(jobId: JobId): PlacementDecisionInfo | undefined;
+    /**
+     * Run the placement engine against AutoManager's current inventory
+     * snapshot and configured pools, without actually placing or
+     * provisioning anything. Powers preview affordances in operator
+     * UIs ("if I submitted this bundle now, where would each replica
+     * land?").
+     *
+     * `jobName` is optional; if omitted the *first* job in the bundle
+     * is used. For multi-job bundles, supply the name to get a decision
+     * specific to that job.
+     *
+     * Returns undefined if the bundle's named job is missing or the
+     * replica index is out of range.
+     * @public
+     */
+    placeDryRun(bundle: TypedBundle, replicaIndex: number, jobName?: string): {
+        result: PlacementResult;
+        trace: PlacementTrace;
+    } | undefined;
+    /**
+     * Static validation of a bundle against AutoManager's currently
+     * configured pools. Equivalent to calling the module-level
+     * `validateBundle` with `PoolDescriptor[]` derived from
+     * `AutoSettings.placementPools` — elastic pools project their
+     * `candidateInstanceTypes` into node profiles; cluster pools project
+     * their currently-known live inventory.
+     * @public
+     */
+    validateBundle(bundle: TypedBundle): ValidationResult;
+    /**
+     * Phase C4 — packaged admission check. Combines `validateBundle`
+     * (static spec sanity) with `placeDryRun` for every (replica,
+     * jobName) pair. Returns `ok` only when both pass for every
+     * member; otherwise reports the structured failure. Use as a
+     * pre-submit guard in operator-facing tooling.
+     *
+     * Per the design's §3.4 band table, all bands reject at admission
+     * on "no capacity right now" — there's no band differentiation
+     * here. (Gold/silver get *queued* internally on capacity-after-
+     * submit failures via the rejection re-place path, but that's a
+     * runtime concern, not admission.)
+     *
+     * @public
+     */
+    validateBundleAdmission(bundle: TypedBundle): AdmissionResult;
+    private poolDescriptorsForValidation;
+    /**
+     * AutoManager v1 — typed inventory snapshot for a single node, or
+     * undefined if the worker hasn't (yet) advertised one.
+     * @public
+     */
+    inventory(nodeId: NodeId): TypedNodeInventory | undefined;
+    /**
+     * AutoManager v1 — typed inventory snapshots for every node we know
+     * about. Iteration order is insertion order.
+     * @public
+     */
+    inventories(): {
+        nodeId: NodeId;
+        inventory: TypedNodeInventory;
+    }[];
+    private handleNodeInventoryUpdated;
+    /**
+     * A running job has had its config updated at runtime (operator action,
+     * job-driven, or other side channel). Refresh our in-memory copy so a
+     * subsequent `redeploy` (placeAndProvision triggered by node failure
+     * etc.) hands the new config rather than the launch one.
+     *
+     * Manager is responsible for persisting the new value; AutoManager
+     * just keeps its mirror up to date.
+     */
+    private handleJobConfigUpdated;
+    private handleJobRejected;
+    private recordRejection;
+    private currentExcludeSet;
+    /**
+     * Phase C2 — restart-rate check. Records the current attempt; if the
+     * trailing-hour count crosses the band's `maxRestartsPerHour`, marks
+     * the bundle broken, fires `onBundleBroken`, and returns true
+     * (caller must short-circuit). Returns false when within budget.
+     */
+    private shouldBreakOnRestart;
+    /**
+     * Whether the named bundle has tripped the restart ceiling and is
+     * being held by AutoManager. Cleared by `bundleUpdated` (operator
+     * pushed a fresh spec) or `bundleDeleted`.
+     * @public
+     */
+    isBundleBroken(bundleId: BundleId): boolean;
+    /**
+     * Initiate a migration of a running job to a target node. AutoManager
+     * provisions a second instance of the same Job on `targetNodeId` with
+     * role="migrationTarget" and drives the cutover handshake. Returns
+     * a stable `migrationId` for tracking.
+     *
+     * Throws if a migration is already in flight for `sourceJobId` (no
+     * concurrent migrations per Job).
+     *
+     * `sourceRole` defaults to whichever role the first node hosting
+     * `sourceJobId` has — adequate for single-instance Jobs. Specify
+     * explicitly for multi-replica bundles.
+     *
+     * @public
+     */
+    migrateJob(sourceJobId: JobId, targetNodeId: NodeId, sourceRole?: Role): Promise<MigrationId>;
+    /**
+     * Abort an in-flight migration. AutoManager sends MigrationAbort to
+     * any live source/target instances and marks the migration aborted.
+     * No-op (with warning log) for an unknown migration id.
+     *
+     * @public
+     */
+    abortMigration(migrationId: MigrationId, reason: string): Promise<void>;
+    /** All known migrations (active + done + aborted). @public */
+    migrations(): MigrationState[];
+    /** Look up a single migration by id. @public */
+    migrationById(migrationId: MigrationId): MigrationState | undefined;
+    /** Migration active for the given source jobId, if any. @public */
+    migrationForJob(jobId: JobId): MigrationState | undefined;
+    /**
+     * Find the role of the (first) node currently running this Job.
+     * Returns undefined if no node hosts the job.
+     */
+    private inferSourceRole;
+    private advanceMigration;
+    /** Phase E deadlines — re-arm the per-phase timer for the migration. */
+    private armMigrationPhaseDeadline;
+    private cfgMigrationPhaseDeadline;
+    private markMigrationDone;
+    private markMigrationAborted;
+    private failMigration;
+    private dispatchMigrationAborts;
+    private handleMigrationTargetReady;
+    private handleMigrationSourceStoppedOutput;
+    private handleMigrationAborted;
+    private findNodeForJobKey;
+    private cfgRejectionBackoffMs;
+    private cfgRejectionEscalationCount;
+    private cfgFailureBackoffMs;
+    private cfgJobStartupGraceMs;
+    private cfgMaxRestartsPerHour;
+    private placeAndProvision;
+    private inventoriesAsNodeViews;
+    /** Map a placed jobId to the RunningJob view the placement engine uses
+     *  for affinity / spread, via the job's bundle-context tags. Empty when
+     *  the job lacks bundle tags. */
+    private runningJobFor;
+    /** Sum the resource requirements of the given placed jobs into a node
+     *  reservation. Capacity / cores / capabilities come from each job's
+     *  bundle spec — the canonical typed requirements the placement engine
+     *  scores against, looked up via the job's bundleId / jobName tags. Jobs
+     *  whose bundle or spec we don't have yet contribute nothing. */
+    private derivedReservation;
+    /** The canonical typed requirements for a placed job, from its bundle
+     *  spec (the same source `placeAndProvision` scores against). */
+    private requirementsForPlacedJob;
+    /**
+     * Phase C5 — is the named node currently tagged as a hot spare?
+     * Spares are warm-running nodes provisioned (by the C6 reconciler)
+     * with `NodeMetadata.tags["spare"] = "true"`. The optional
+     * `tags["spareBand"]` ("gold" | "silver") dedicates a spare to a
+     * band; if absent, the spare is band-agnostic.
+     * @public
+     */
+    isHotSpareNode(nodeId: NodeId): boolean;
+    /**
+     * Phase C5 — band a spare is dedicated to, if any. `undefined` for a
+     * non-spare or for a band-agnostic spare.
+     * @public
+     */
+    spareBandForNode(nodeId: NodeId): PriorityBand | undefined;
+    /**
+     * Drive every configured `hotSpares` entry toward its `targetCount`.
+     * Counts live + pending spares matching (pool, band); provisions
+     * short, terminates excess (oldest live first). Cluster pools are
+     * non-elastic — under-target just fires `onSpareUnderflow` and
+     * leaves provisioning to the operator. Idempotent and cheap; safe
+     * to call on every lifecycle event plus the periodic tick.
+     */
+    private reconcileHotSpares;
+    private spareNodesMatching;
+    private pendingSparesMatching;
+    private provisionHotSpare;
+    /**
+     * @public
+     * Current placements for each configured NodeService. Returns a
+     * snapshot map of `serviceId → (nodeId → runtimeJobId)`.
+     */
+    nodeServices(): NodeService[];
+    /**
+     * @public
+     * Nodes on which the named NodeService is currently placed,
+     * keyed by the runtime job's jobId.
+     */
+    nodeServicePlacementsFor(serviceId: ServiceId): Map<NodeId, JobId>;
+    /**
+     * Drive every configured NodeService toward its lifecycle target.
+     * v1 only handles `eager` — places on every eligible node.
+     * `lazy` placements + capability-loss-driven consumer recovery (F3)
+     * are deferred.
+     */
+    private reconcileNodeServices;
+    private reconcileEagerNodeService;
+    /**
+     * Identify nodes in the service's named pools whose current inventory
+     * satisfies its `consumes` requirements. Used both for placement and
+     * for tear-down decisions.
+     */
+    private eligibleNodesForService;
+    private nodeSatisfiesConsumes;
+    private placeNodeService;
+    private teardownNodeService;
+    private tagsForJob;
+    private poolNameForNode;
+    private tierNameForNode;
+    private azForNode;
+    private cloudForNode;
+    private handleBundleUpdated;
+    private handleBundleDeleted;
+    private clearRestartHistoryForBundle;
+    private nodesByJob;
+    private handleJobChanged;
+    /** Read the `__stopDateTime` tag off the job, and (re)schedule the
+     *  bundle's stop timer accordingly. Tag is set per-job but applies
+     *  to the whole bundle — first-job-wins for read; all jobs in a
+     *  bundle share the same value at submit. */
+    private reconcileStopTimer;
+    private scheduleStopTimer;
+    /**
+     * Update (or clear) a bundle's auto-stop time. Calls `updateBundle`
+     * so the new value persists via the daemon's tag store and any other
+     * clients see it through their event streams. Pass `undefined` to
+     * cancel a previously-set stop time.
+     *
+     * Throws if the bundle isn't known to this AutoManager (no live
+     * bundleMap entry); operators wanting to set stop on a not-yet-
+     * streamed bundle should retry after JobPending fires.
+     * @public
+     */
+    setBundleStopTime(bundleId: BundleId, stopDateTime?: Date): Promise<void>;
+    /**
+     * Snapshot of all currently-scheduled bundle stop timers. UIs render
+     * this alongside `pendingPlacements()` for an "upcoming events"
+     * view.
+     * @public
+     */
+    bundleStopTimes(): Array<{
+        bundleId: BundleId;
+        stopAt: Date;
+    }>;
+    /** A job that should be running but currently has no node bound to
+     *  it: it carries placement `requirements`, isn't manual-start, is in
+     *  a placeable state (`pre` / `active`), and `nodesByJob` is empty.
+     *  This is the single source of truth for "this job wants a placement
+     *  and doesn't have one" — shared by initial hydration, the per-job
+     *  `handleJobChanged` path, and the capacity-driven reconcile sweep,
+     *  so the decision lives in exactly one place. */
+    private wantsPlacementNow;
+    /**
+     * Re-run placement for every job that wants a node but hasn't got
+     * one. Called whenever a *capacity-increasing* event arrives — a node
+     * comes online (`nodeStarted`), a worker reports fresh inventory
+     * (`nodeInventoryUpdated`, which also covers an un-cordon or a node
+     * that has just freed reserved capacity), or a job finishes and
+     * releases its node (`jobDeleted`). Those are the only transitions
+     * that can turn a previously-unplaceable job placeable, so they are
+     * exactly when re-running the engine is worthwhile — there is no
+     * polling retry, the trigger is always a concrete event.
+     *
+     * Placement stays implemented once: each candidate routes through
+     * `placeOrDefer` (the same entry point hydration and `handleJobChanged`
+     * use), inheriting its scheduling, the in-flight gate, and the
+     * failure path. Jobs already waiting on a schedule timer or a recovery
+     * backoff are skipped — their own timers own them — so a capacity
+     * event never disturbs a future-scheduled or backing-off job.
+     *
+     * Cheap and idempotent (mirrors `reconcileHotSpares` /
+     * `reconcileNodeServices`); safe to call on every relevant event.
+     */
+    private reconcilePendingPlacements;
+    /** Decide whether to place immediately or defer until the job's
+     *  scheduled `startDateTime` (minus pool lead time) arrives.
+     *  Re-entry from job-update events: cancels and re-evaluates so a
+     *  schedule change moves the timer. Hydrated jobs with `startTime -
+     *  lead` in the past place immediately (operator intent was to run;
+     *  schedule was a "when", not a "drop if missed"). */
+    private placeOrDefer;
+    /** Maximum `placementLeadMs` across the bundle pool's tiers (worst case
+     *  — guarantees the job is ready by `startDateTime` regardless of which
+     *  tier the placement engine ends up picking). Falls back to the per-kind
+     *  default when a tier doesn't specify one. Returns 0 if the bundle or
+     *  pool isn't found — we'd rather race the schedule than indefinitely
+     *  delay placement. */
+    private placementLeadMsForJob;
+    /**
+     * Currently-scheduled placements (jobs AutoManager has deferred
+     * because their `startDateTime - leadTime` is still in the future).
+     * Returns one entry per pending timer; the UI can render an
+     * "upcoming jobs" list and show when each will go live.
+     * @public
+     */
+    pendingPlacements(): Array<{
+        jobId: JobId;
+        scheduledFor: Date;
+    }>;
+    private handleJobDeleted;
+    private handleNodeStarting;
+    /** Phase C3. Schedule the grace timer; replace any prior timer. */
+    private armStartupGrace;
+    private cancelStartupGrace;
+    private handleNodeStarted;
+    private advanceMigrationsOnNodeStarted;
+    private handleNodeStopping;
+    private handleNodeStopped;
+    private dropNodeServicePlacementsOnNode;
+    private updateNodeMap;
+}
+export declare function getJobIdForNode(nodeMetadata: NodeMetadata | undefined): JobId | undefined;
+/**
+ * Walk a job's history backward and return the nodeId where it is
+ * currently placed (or was most recently placed). Prefers `running`
+ * entries; falls back to `provisioned` for jobs still booting their
+ * node. Returns undefined for jobs that have never been placed or
+ * whose history is empty (defensive — runtime data always has at
+ * least a `created` entry, which carries no nodeMetadata).
+ *
+ * This is the canonical "where does this job live" lookup and
+ * underpins `AutoManager.nodeForJob`. It works regardless of whether
+ * a node hosts one job (cloud, today) or many (cluster, or future
+ * cloud N:1) because the nodeId is recorded against the JOB rather
+ * than scanned out of NODE tags.
+ */
+export declare function currentNodeIdForJob(jh: JobWithHistory | undefined): NodeId | undefined;
+//# sourceMappingURL=automanager.d.ts.map