norsk-manager-sdk package

Classes

Class Description

NorskManager

The entrypoint for all Norsk Manager applications

Functions

Function Description

classifyProtocolSkew(ours, theirs)

Classify theirs against ours. Direction does not matter. An absent or all-zero version (an empty message on the wire) is unknown, never major.

eventStream(norsk, options)

fromActiveJobKey(key)

fromProductTemplateRef(ref)

toActiveJobKey(key)

toProductTemplateRef(ref)

Interfaces

Interface Description

ActiveJobKey

Identifies a specific instance of a Job. (jobId, role) is unique within Manager; a 2-replica bundle has two ActiveJobKeys sharing jobId but with different role (e.g. "primary"/"backup").

role is the instance KEY Manager routes by. It is usually the same string as the slot the job is told in NORSK_RUNTIME_ROLE, but a migration target wears a key unique to its migration (e.g. "primary@3f9c1e2a") while its slot stays "primary", so the source and the target of one migration are addressable distinctly.

AuditAppendedEvent

A new audit-log entry was appended on the daemon (any source). Unlike the AutoManager raw-PB events, this carries the SDK’s own AuditLogEntry — the audit domain type lives in the SDK (it’s what getAuditLog returns), so the conversion happens here rather than in consumers.

AuditLogEntry

/** One entry in the daemon’s durable, hash-chained audit log. seq is narrowed from the wire int64 to a number (entry counts stay well within 2^53). payload is opaque (already-serialised JSON or text).

AwsHealth

AwsLaunchTemplateId

AwsLaunchTemplateName

AwsNodeCreate

AwsRootVolume

The root volume an AWS node is launched with. The device name is the AMI’s business, not the caller’s.

BundleDeletedEvent

BundleUpdatedEvent

ClusterNodeInfo

Snapshot of a cluster slot returned from listClusterNodes.

active is true when the worker’s gRPC stream is currently connected. When inactive, listenAddress / listenPort / hardware reflect the last known values (or are empty/zero if the worker has never registered).

ClusterRegistration

CurrentJob

DaemonHello

What the Manager daemon said about itself when the status channel opened. protocolVersion is absent for a daemon that predates the handshake, in which case skew is "unknown". daemonVersion is the daemon’s build label (version.label), which stands in when the daemon sent no separate daemon_version.

DateFilter

Filters jobs by their START time. The wire carries only the comparison and the Manager applies it to startTime; there is no end-time filter. (An earlier dateType: "start" | "end" field was accepted and ignored, so an "end" filter silently filtered on start time; it is gone.)

EventStreamClosed

The manager activity stream has closed

EventStreamInitialState

EventStreamSettings

Configuration for creating an event stream

GpuInfo

Hardware capabilities a cluster worker reports during registration. v1 carries cpu count + total memory; gpu / sdi / network arrays are placeholder shapes for a later sub-phase.

HardwareInfo

HydrationDrop

A persisted row a daemon store couldn’t parse on the current boot (schema drift / corruption). The live set — clears when a later boot hydrates cleanly. key is the RocksDB key; store the producer.

IdFilter

ImagesPrefetchedEvent

Warm nodes, Phase G. A prefetch batch has settled on raw.nodeId: raw.results carries one entry per requested ref, each saying for itself whether it landed and what digest it resolved to. A failure on one ref says nothing about the others. The node’s NodeInventory.heldImages is re-advertised right behind this event.

Job

JobDeleted

A job has been deleted

JobInfo

Informational messages about a job

JobOutOfWindow

A job has been updated such that it no longer matches the search criteria

JobPending

Job is almost ready to start - "almost" defined by property passed into the list functions - todo, sort out this description

JobRejectedEvent

JobSearchSettings

JobUpdated

Job details have been updated

JobWithHistory

MigrationAbortedEvent

Migration handshake event. A worker workflow has reported it cannot continue the handshake for raw.migrationId; AutoManager aborts.

MigrationInitialStateDeliveredEvent

Migration handshake event. The worker has delivered the source’s state (the migrationInitialState from StartJob) to the target instance of raw.migrationId over its job socket. Ends AutoManager’s settingStateOnTarget phase; the target’s ready follows separately.

MigrationSourceStoppedOutputEvent

Migration handshake event. The source instance of raw.migrationId has stopped output at the position in raw.payload. AutoManager relays the payload to the target via NotifyMigrationCutoverApply.

MigrationStateEvent

Migration handshake event, Phase F — the propose. The SOURCE instance of raw.migrationId has answered "what state would you hand over?" with either raw.payload (opaque; empty is a valid acceptance) or a non-empty raw.refused, which ends the migration before any target has been placed. The refusal is on the envelope, so a coordinator never opens the blob to learn it was turned down.

MigrationTargetAppliedEvent

Migration handshake event. The target instance of raw.migrationId has applied the handover and begun output; only now does AutoManager stop the source.

MigrationTargetReadyEvent

Migration handshake event. The target instance of raw.migrationId is ready to begin output from the position in raw.payload (opaque: the job owns its meaning). AutoManager owns the protocol and relays the payload to the source; SDK consumers see the raw PB.

NetworkInfo

NodeInventoryUpdatedEvent

NodePending

A node is pending

NodeRunning

A node is running - used in initial state messages

NodeStarting

A node is starting

NodeStopped

A node has stopped

NodeStopping

A node is stopping

NoFilter

NorskSettings

Top level Norsk configuration

OciHealth

Per-availability-domain health, mirroring AwsHealth.regions.

OciNodeCreate

ProductTemplateRef

Identifies a product-template tar — opaque to Manager, resolved by the worker at launch time. sha256 is the canonical cache key (lowercase hex of the tar’s SHA-256). The same tar may arrive via different transports (URL, inline bytes, content-addressed lookup) but its cache entry is one and the same.

See .ai/steve/tasks/39-blueprint-jobs.md for the full design.

ProtocolVersion

A wire-protocol version as sent in a Hello (norsk.api.common.ProtocolVersion).

ProviderHealthChange

;

The health status of a provider has changed

SdiInfo

StartJobOptions

Job-migration fields on startJob, forwarded verbatim to the worker. All optional; a plain start passes none of them.

StateFilter

StopJobOptions

Options on stopJob. migrationId marks the stop as the source side of that migration, recorded in the job’s history as "migration".

TagFilter

VersionInfo

Norsk Manager Version information

WorkerSecurityGroupInfo

A security group dev-ops marked selectable for workers by tagging it id3as.Norsk.WorkerSecurityGroup = <label>. The label is the portable name launches select by; rule detail comes from the SG itself.

WorkerSecurityGroupRule

One ingress permission on a worker security group, flattened for launch-UI port hints. protocol is "tcp" | "udp" | "icmp" | "-1" — "-1" means all traffic (ports are 0 and the rule covers every port).

WorkerSecurityGroups

Discovery result for a region: the selectable (tagged) groups plus the base worker SG(s) every worker always carries — included so a launch UI can treat ports the deployment substrate already opens as covered. label is empty on base groups.

Variables

Variable Description

DEFAULT_UNARY_DEADLINE_MS

The deadline every unary call carries unless NorskSettings.unaryDeadlineMs says otherwise: 30 s. Generous for the slowest honest answer (a bundle expansion, an EC2 describe) and short enough that a Manager which accepts TCP but never answers fails the call rather than hanging it forever.

emptyHardwareInfo

PROTOCOL_VERSION_MAJOR

PROTOCOL_VERSION_MINOR

PROTOCOL_VERSION

The wire-protocol version, <major>.<minor>.0.

SDK_PROTOCOL_VERSION

The SDK’s own protocol version, as a ProtocolVersion.

Type Aliases

Type Alias Description

AwsEbsVolumeType

AwsInstanceId

AwsInstanceType

AwsMetadata

AwsNodeId

AwsRegion

BindMount

ClientCode

Cloud

ClusterMetadata

ContainerPort

ContainerUrl

CreateJob

DaemonVersion

DateComparison

DockerContainer

EnvironmentVariable

EphemeralHostPort

EventStreamEvent

FileContent

Health

HostPort

IdComparison

JobFilter

JobHistoryEntry

JobHistoryJobCompleted

JobHistoryJobCreated

JobHistoryJobPrepared

An instance started with deferStart has every container created and is waiting for startPreparedJob. Sits between provisioned and running for that instance (the stop-then-start migration strategy).

JobHistoryJobProvisioned

JobHistoryJobRejected

JobHistoryJobRunning

JobHistoryJobStopped

JobHistoryJobStopping

JobHistoryJobUpdated

JobId

JobListEvent

List of events that can be raised by the jobList API - TODO - link

JobState

Log

NodeId

NodeInfo

State of a node

NodeInterruptionKind

Why a provider is taking a node back. spotInterruption is the terminal warning (EC2 gives two minutes; deadline says when); a rebalanceRecommendation says the capacity is at elevated risk, carries no time, and is usually followed by the interruption itself.

NodeInterruptionNotice

The provider is reclaiming nodeId. Raised by the daemon from the worker’s own report (the instance metadata service is reachable only from the instance). The daemon tags the node interruption=<kind> at the same time, so a client hydrating from listNodes sees it too. The AutoManager drains the node on this (handleNodeInterruption).

NodeMetadata

NodeStarted

A node has started

NodeTagsUpdated

A node’s tags changed. The one producer today is a hot spare being given a job: the daemon drops spare from the node’s tags the moment a job is bound to it, so a spare is a spare until it is assigned a job and an ordinary node after. Carries the node’s metadata as it now stands.

NorskVersion

OciAvailabilityDomain

OciInstanceId

OciMetadata

OciRegion

PortMapping

ProtocolSkew

How a peer’s protocol version compares to ours: - none: same major and minor. - minor: same major, different minor — additive drift, accept and warn. - major: different major — incompatible, refuse. - unknown: the peer sent no version (it predates the handshake) — warn.

ProviderHealth

ProviderMetadata

RangePort

RestartIntensity

Role

RunningAwsMetadata

RunningClusterMetadata

RunningJob

RunningNodeMetadata

RunningNodeProviderMetadata

RunningOciMetadata

Service

ServiceParameters

ServiceRestart

SpecificHostPort

StateComparison

TagComparison

Ulimit

VolumeMount

WriteFile