@kici-dev/orchestrator 0.17.0 → 0.18.0

package/dist/agent/host-roster-reaper.d.ts

@@ -9,20 +9,18 @@ export interface HostRosterReaperOptions {
     setUnreachableGauge: (value: number) => void;
 }
 /**
- * Leader-only host-roster reaper.
- *
- * Modeled on `EventRetryScanner`: started/stopped via the Raft leadership
- * callbacks, a single timer cleared on `stop()`. Each leader tick it:
+ * Leader-only host-roster reaper, started/stopped via the Raft leadership
+ * callbacks like `EventRetryScanner`. Each leader tick it:
  *
  * - DELETEs `ephemeral` host_roster rows whose `last_seen` is older than the ttl
  *   (scaled-down autoscale agents — silent GC, no alarm); and
- * - counts `static` (declared) hosts whose derived status is `unreachable` and
- *   publishes that count to the `kici_orch_declared_hosts_unreachable` gauge, so
- *   a Mimir ruler alert can page an operator when a declared box goes dark.
+ * - publishes the count of `static` (declared) hosts whose derived status is
+ *   `unreachable` to the `kici_orch_declared_hosts_unreachable` gauge, so a
+ *   Mimir ruler alert can page an operator when a declared box goes dark.
  *
- * `static` unreachability is read-derived by `deriveHostStatus` (no write here),
- * so the reaper never deletes a static row. Followers never run the reaper, so
- * the gauge series exists only on the leader (the alert uses `max by ()`).
+ * `static` unreachability is read-derived by `deriveHostStatus`, so the reaper
+ * never deletes a static row. The gauge series exists only on the leader (the
+ * alert uses `max by ()`).
  */
 export declare class HostRosterReaper {
     private readonly store;

package/dist/agent/host-roster.d.ts

@@ -17,11 +17,10 @@ export declare const STAGED_AGENT_VERSION_KEY = "kici:staged-agent-version";
 export declare function isReservedHostKey(key: string): boolean;
 /**
  * Drop every reserved `kici:` key from an agent-reported host-property bag.
- * Agent-reported properties win the roster shallow-merge, and the staged-version
- * convergence gate and the restart commands the re-stage runs over SSH both
- * read `kici:` keys, so a registering agent must never set them. Reserved keys
- * come only from orchestrator code (`recordStagedVersion`) and a local
- * `kici-admin host declare`.
+ * Agent keys win the roster shallow-merge, and the staged-version convergence
+ * gate and the re-stage's SSH restart commands read `kici:` keys, so an agent
+ * must never set them. Reserved keys come only from `recordStagedVersion` and
+ * a local `kici-admin host declare`.
  */
 export declare function stripReservedProperties(props: HostProperties): HostProperties;
 /** Who is writing a static host declaration or removal. */
@@ -65,10 +64,9 @@ export interface DeclareStaticInput {
     authority?: HostWriteAuthority;
 }
 /**
- * Pre-agent reach metadata for a declared host — how to SSH to it for bootstrap
- * bring-up before it has a KiCI agent. All fields nullable: a host with no reach
- * metadata cannot be bootstrapped. `sshKeySecret` is a scoped-secret ref
- * (`scope/key`) the orchestrator resolves server-side; the key never lives here.
+ * How to SSH to a declared host for bootstrap bring-up before it has an agent.
+ * A host with no reach metadata cannot be bootstrapped. `sshKeySecret` is a
+ * scoped-secret ref (`scope/key`) resolved server-side; the key never lives here.
  */
 export interface HostReach {
     agentId: string;
@@ -77,9 +75,9 @@ export interface HostReach {
     sshPort: number | null;
     sshKeySecret: string | null;
     /**
-     * When true, the box can reach the orchestrator's object storage — bring-up
-     * picks the `s3-direct` delivery mode (box pulls the payload via a presigned
-     * URL). NULL / false ⇒ the conservative `ssh-push` fallback.
+     * True ⇒ the box reaches the orchestrator's object storage, so bring-up uses
+     * `s3-direct` (the box pulls the payload via a presigned URL). NULL / false ⇒
+     * the conservative `ssh-push` fallback.
      */
     s3Reachable: boolean | null;
 }
@@ -99,19 +97,17 @@ export declare enum HostStatus {
 /** The lifecycle class snapshot from the auth token's `agent_type`. */
 export type LifecycleClass = 'static' | 'ephemeral';
 /**
- * A roster host that matched a `runsOnAll` predicate, with its derived status.
- * The host-fanout resolver consumes this: `ready` hosts become pinned children;
- * `unreachable` static hosts are subject to the `onUnreachable` policy; `stale`
- * ephemeral hosts are skipped.
+ * A roster host that matched a `runsOnAll` predicate. In the host-fanout
+ * resolver, `ready` hosts become pinned children, `unreachable` static hosts
+ * get the `onUnreachable` policy, and `stale` ephemeral hosts are skipped.
  */
 export interface MatchedHost {
     agentId: string;
     /** Canonical hostname; falls back to the raw agentId when the row has none. */
     host: string;
     /**
-     * The row's labels, folded on read. A row written before labels were
-     * canonicalized still carries the case the operator typed, and this is the
-     * only place that case would otherwise reach a matcher.
+     * Folded on read: a row written before labels were canonicalized keeps the
+     * operator's case, and this is the only place it would otherwise reach a matcher.
      */
     labels: CanonicalLabel[];
     lifecycleClass: LifecycleClass;
@@ -128,10 +124,9 @@ export interface UpsertHostInput {
     tokenId: string | null;
     lifecycleClass: LifecycleClass;
     /**
-     * True when an auto-scaler backend spawned this agent, so `runsOnAll`
-     * fan-out skips it. Derived from the scaler manager's registration lookup,
-     * never from `lifecycleClass` (which is `ephemeral` for every agent when the
-     * auth mode is `none`). Omitted ⇒ false.
+     * True when an auto-scaler spawned this agent, so `runsOnAll` fan-out skips
+     * it. From the scaler manager's registration lookup, never `lifecycleClass`
+     * (`ephemeral` for every agent under auth mode `none`). Omitted ⇒ false.
      */
     scalerManaged?: boolean;
     labels: string[];
@@ -140,9 +135,8 @@ export interface UpsertHostInput {
     arch: string;
     instanceId: string;
     /**
-     * Agent-reported typed host-vars. Shallow-merged into any existing bag on
-     * conflict (agent-reported keys win; operator-declared keys the agent does
-     * not report are preserved). Omitted ⇒ no change to the stored bag on update,
+     * Shallow-merged into the existing bag on conflict: agent keys win, operator
+     * keys the agent does not report survive. Omitted ⇒ no change on update,
      * `{}` on insert.
      */
     properties?: HostProperties;
@@ -154,30 +148,27 @@ export interface HostStatusRow {
     last_seen: Date | string;
 }
 /**
- * The ONE status-derivation function — used by the store and the kici-admin
- * host CLI. `ready` requires the host to be genuinely live (connected to some
- * instance AND heartbeat fresh — the freshness check catches a crashed
- * instance that never cleared `connected_instance_id`). It never returns
- * `ready` for a not-currently-live host: a not-live `static` reads
- * `unreachable` (the declared-but-absent alarm), a not-live `ephemeral` reads
- * `stale` (scaled down, awaiting reap).
+ * The ONE status derivation, shared by the store and the kici-admin host CLI.
+ * `ready` needs a connected instance AND a fresh heartbeat (freshness catches a
+ * crashed instance that never cleared `connected_instance_id`). A not-live
+ * `static` reads `unreachable` (the declared-but-absent alarm); a not-live
+ * `ephemeral` reads `stale` (scaled down, awaiting reap).
  */
 export declare function deriveHostStatus(row: HostStatusRow, nowMs: number, graceMs: number): HostStatus;
 /**
- * Normalize a stored `host_properties` value into a typed host-vars bag. The pg
- * driver returns parsed JSON for a `jsonb` column, but accept a JSON string too
- * (defensive for non-pg paths / tests). Non-object / null reads back as `{}`.
+ * Normalize a stored `host_properties` value. pg returns parsed `jsonb`; a JSON
+ * string is accepted for non-pg paths and tests. Non-object / null reads `{}`.
  */
 export declare function parseHostProperties(value: unknown): HostProperties;
 /**
  * Durable, cluster-shared roster of every agent the cluster has ever enrolled.
  *
- * The in-memory `AgentRegistry` reconciles into this table on register
- * (`upsert`) / unregister (`markDisconnected`), with a coarse heartbeat
- * (`stampLastSeen`). All liveness writes are owner-guarded by `instanceId` so a
- * stale disconnect from an old instance can never clobber a row a different
- * instance now owns. The leader-only reaper deletes `ephemeral` rows past their
- * ttl via `reapEphemeralPastTtl`; `static` rows persist and read `unreachable`.
+ * The in-memory `AgentRegistry` reconciles into it on register (`upsert`),
+ * unregister (`markDisconnected`) and a coarse heartbeat (`stampLastSeen`).
+ * Liveness writes are owner-guarded by `instanceId`, so a stale disconnect from
+ * an old instance never clobbers a row another instance now owns. The
+ * leader-only reaper deletes `ephemeral` rows past ttl; `static` rows persist
+ * and read `unreachable`.
  */
 export declare class HostRosterStore {
     private readonly db;
@@ -189,10 +180,9 @@ export declare class HostRosterStore {
     /** Coarse heartbeat stamp — same owner-guard as markDisconnected. */
     stampLastSeen(agentId: string, instanceId: string): Promise<void>;
     /**
-     * Declare a static host. Under `operator` authority (a local `kici-admin`),
-     * it inserts or converges the row; under `platform` authority (a dashboard
-     * write, the default) it only creates a new, unconfirmed row. Returns
-     * `{ created: true }` when the declare inserted the row.
+     * Declare a static host. `operator` authority (a local `kici-admin`) inserts
+     * or converges the row; `platform` authority (a dashboard write, the default)
+     * only creates a new, unconfirmed row. `created` is true when it inserted.
      */
     declareStatic(input: DeclareStaticInput): Promise<{
         created: boolean;
@@ -206,14 +196,13 @@ export declare class HostRosterStore {
     /**
      * An operator declare. A re-declare converges the operator-owned columns
      * (labels, hostname, reach, host_properties) and preserves the agent-reported
-     * liveness and identity columns (connected_instance_id, last_seen, platform,
-     * arch, lifecycle_class, token_id, reboot_pending_until). Each operator field
-     * is preserve-on-omit, and properties shallow-merge — except on a row a
-     * dashboard declare created: there the operator's values replace labels,
-     * hostname and properties outright, so no Platform-chosen value survives the
-     * confirmation, and the row becomes `operator`. An `agent` row stays `agent`.
-     * PostgreSQL evaluates every SET expression against the existing row, so each
-     * CASE reads the source before this statement changes it.
+     * ones (connected_instance_id, last_seen, platform, arch, lifecycle_class,
+     * token_id, reboot_pending_until). Operator fields are preserve-on-omit and
+     * properties shallow-merge — except on a dashboard-declared row, where the
+     * operator's labels, hostname and properties replace it outright (no
+     * Platform-chosen value survives confirmation) and the row becomes
+     * `operator`. An `agent` row stays `agent`. PostgreSQL evaluates every SET
+     * against the existing row, so each CASE reads the source before the update.
      */
     private declareAsOperator;
     /**
@@ -223,12 +212,11 @@ export declare class HostRosterStore {
     getReach(agentId: string): Promise<HostReach | null>;
     get(agentId: string): Promise<HostRosterRow | null>;
     /**
-     * Record the self-contained agent-payload version the orchestrator staged onto
-     * a host (bring-up or fleet re-stage). Stored in `host_properties` under a
-     * reserved key so the convergence gate can compare it against the target
-     * INDEPENDENTLY of the agent's own self-reported bundle version (two payloads
-     * can carry the same self-report but different staged keys). Shallow-merged, so
-     * it survives an agent re-register (the agent's reserved keys are stripped).
+     * Record the agent-payload version staged onto a host (bring-up or fleet
+     * re-stage), under a reserved key, so the convergence gate compares it to the
+     * target INDEPENDENTLY of the agent's self-reported version (two payloads can
+     * share a self-report but differ in staged key). Shallow-merged, so it survives
+     * an agent re-register (the agent's reserved keys are stripped).
      */
     recordStagedVersion(agentId: string, version: string): Promise<void>;
     /** Read a host's recorded staged agent-payload version, or null when never staged. */
@@ -238,50 +226,42 @@ export declare class HostRosterStore {
     private listConfirmed;
     /**
      * Resolve EVERY roster host matching a label predicate (OR-of-AND include
-     * groups, minus exclude labels), tagged with its derived status. Returns
-     * declared-but-absent static hosts (status `unreachable`) so a caller can
-     * apply `onUnreachable` — the live registry alone cannot name an
-     * expected-but-absent host.
+     * groups, minus exclude labels), with derived status. Declared-but-absent
+     * static hosts come back `unreachable` so a caller can apply `onUnreachable`;
+     * the live registry alone cannot name them.
      *
-     * This is the INVENTORY query: it includes auto-scaler-spawned hosts, whose
-     * `lifecycleClass` is what the SDK's `ctx.kici.inventory` exposes to tell
-     * them apart. `runsOnAll` fan-out uses {@link findFanoutTargets} instead.
+     * The INVENTORY query: it includes auto-scaler hosts, told apart by the
+     * `lifecycleClass` `ctx.kici.inventory` exposes. `runsOnAll` fan-out uses
+     * {@link findFanoutTargets} instead.
      */
     findMatching(include: readonly (readonly LabelMatcher[])[], exclude: readonly LabelMatcher[], graceMs: number): Promise<MatchedHost[]>;
     /**
-     * Resolve the `runsOnAll` fan-out target set: {@link findMatching}, minus
-     * every auto-scaler-spawned host.
+     * The `runsOnAll` fan-out targets: {@link findMatching} minus every
+     * auto-scaler host. Fan-out targets DECLARED fleet members: a scaler agent
+     * has a pool's fixed shape, so a child pinned to one runs at that shape — the
+     * defect the dispatcher's warm-pool suitability gate removes, on the path a
+     * pin deliberately leaves ungated.
      *
-     * Fan-out targets DECLARED fleet members. An auto-scaler agent is spawned to
-     * a pool's fixed shape, so a child pinned to one runs at that shape rather
-     * than its own — the same defect the dispatcher's warm-pool suitability gate
-     * removes, on the path a pin deliberately leaves ungated.
-     *
-     * Separate from `findMatching` on purpose: `findMatching` also backs the
-     * SDK's `inventory.query`, where a host the caller asked for must never go
-     * missing (a selector returning FEWER hosts than no selector at all).
+     * Separate on purpose: `findMatching` also backs `inventory.query`, where a
+     * selector must never return FEWER hosts than no selector at all.
      */
     findFanoutTargets(include: readonly (readonly LabelMatcher[])[], exclude: readonly LabelMatcher[], graceMs: number): Promise<MatchedHost[]>;
     /**
-     * Shared row loop behind {@link findMatching} and {@link findFanoutTargets}.
-     * `excludeScalerManaged` stays private to the store — each public method
-     * names its own semantics, so a call site cannot silently pick the wrong
-     * population by passing a bare boolean.
+     * Shared row loop. `excludeScalerManaged` stays private so a call site cannot
+     * pick the wrong population by passing a bare boolean.
      */
     private matchRows;
     /**
-     * Map a roster row to the canonical {@link HostInventoryEntry} — the queryable
-     * shape returned by the `inventory.query`/`inventory.get` RPC and typed on the
-     * SDK's `ctx.kici.inventory`. Status is derived the same way `findMatching`
-     * derives it (live + fresh ⇒ ready; declared-but-absent static ⇒ unreachable;
-     * ephemeral past ttl ⇒ stale).
+     * Map a roster row to the {@link HostInventoryEntry} the `inventory.query` /
+     * `inventory.get` RPC returns and `ctx.kici.inventory` types. Status derives
+     * as in `findMatching`.
      */
     toInventoryEntry(row: HostRosterRow, graceMs: number): HostInventoryEntry;
     /**
-     * Query the roster as canonical {@link HostInventoryEntry} records. With a
-     * selector, reuses `findMatching`'s label filtering (server-side, glob/regex);
-     * property filtering is done client-side in the workflow. Omit the selector ⇒
-     * every host. Unconfirmed rows a dashboard declare created are omitted.
+     * Query the roster as {@link HostInventoryEntry} records. A selector reuses
+     * `findMatching`'s server-side label filtering (glob/regex); property
+     * filtering happens client-side in the workflow. No selector ⇒ every host.
+     * Unconfirmed dashboard-declared rows are omitted.
      */
     queryInventory(selector: InventorySelector | undefined, graceMs: number): Promise<HostInventoryEntry[]>;
     /** Single-host inventory lookup; null when the agent is absent or unconfirmed. */
@@ -293,13 +273,11 @@ export declare class HostRosterStore {
     /** One roster host for the dashboard, or null when the agent id has no row. */
     getFleetHost(agentId: string, graceMs: number): Promise<FleetHostEntry | null>;
     /**
-     * Count `static` (declared) hosts whose derived status is `unreachable` —
-     * the "declared-but-absent" alarm population. Reuses the single-source
-     * {@link deriveHostStatus} so the count never diverges from what
-     * `kici-admin host list` shows. A not-currently-connected static host reads
-     * `unreachable` regardless of grace (only the connected-but-stale case
-     * depends on `graceMs`). An unconfirmed dashboard-created row never raises
-     * the alarm.
+     * Count `unreachable` static hosts — the declared-but-absent alarm. Uses
+     * {@link deriveHostStatus} so it matches `kici-admin host list`. A
+     * disconnected static host is `unreachable` regardless of grace; only the
+     * connected-but-stale case depends on `graceMs`. An unconfirmed
+     * dashboard-created row never raises the alarm.
      */
     countStaticUnreachable(graceMs: number): Promise<number>;
     /**
@@ -314,9 +292,8 @@ export declare class HostRosterStore {
     /** Delete ephemeral rows whose last_seen is older than ttl. Returns count. */
     reapEphemeralPastTtl(ttlMs: number): Promise<number>;
     /**
-     * Mark a host as about-to-reboot until `until`. Set by the `host.requestReboot`
-     * API handler when an agent's `restartHost()` step runs. While the value is in
-     * the future, the host's disconnect is the expected reboot and its pinned
+     * Set by the `host.requestReboot` handler when an agent's `restartHost()` step
+     * runs. Until `until`, a disconnect is the expected reboot and the pinned
      * post-restart job is held.
      */
     setRebootPending(agentId: string, until: Date): Promise<void>;

package/dist/agent/ownership-refusal.d.ts

@@ -2,11 +2,9 @@
  * The single refusal wording sent to an agent whose job-scoped frame was not
  * accepted on ownership grounds.
  *
- * Deliberately identical whether the database decided "not owned" or could not
- * decide at all. A caller that could tell the two apart would hold an oracle for
- * job existence, upload-commit state, and orchestrator database health — so the
- * two cases are indistinguishable on the wire, and the distinction lives only in
- * the orchestrator's own logs.
+ * Identical whether the database decided "not owned" or could not decide:
+ * telling them apart would be an oracle for job existence, upload-commit state
+ * and database health, so the distinction lives only in the orchestrator logs.
  */
 export declare const OWNERSHIP_REFUSED = "this job is not owned by this agent";
 //# sourceMappingURL=ownership-refusal.d.ts.map

package/dist/agent/ownership-tracker.d.ts

@@ -1,23 +1,14 @@
 /**
- * Job ownership tracker for agent message validation.
- *
  * Validates that agents only send messages (job.status, log.chunk, step.status,
- * job.heartbeat, cache.upload.request, cache.upload.complete) for jobs that were
- * actually dispatched to them.
- *
- * Includes:
- * - Ownership check via dispatcher's isJobOwnedByAgent
- * - Violation counting with sliding window (default: 5 violations in 60s)
- * - Escalation: disconnect agent after threshold violations
+ * job.heartbeat, cache.upload.request, cache.upload.complete) for jobs
+ * dispatched to them. Violations are counted in a window (default: 5 in 60s);
+ * reaching the threshold disconnects the agent.
  */
 /**
- * Verdict of the DB-backed ownership lookup.
- *
- * `unknown` is the load-bearing member: it separates "the database says this
- * agent does not own the job" (evidence of a misrouted or spoofed frame) from
- * "the lookup could not be answered" (a query failure or a timeout). Only the
- * former is a violation — counting an unanswerable check as evidence would let
- * one transient database outage disconnect every connected agent at once.
+ * Verdict of the DB-backed ownership lookup. `unknown` (query failure or
+ * timeout) is distinct from `not-owned` (evidence of a misrouted or spoofed
+ * frame): only `not-owned` is a violation, else one transient database outage
+ * would disconnect every connected agent at once.
  */
 export type OwnershipDbResult = 'owned' | 'not-owned' | 'unknown';
 /** Deadline for a single DB-backed ownership lookup before it resolves `unknown`. */
@@ -26,25 +17,19 @@ interface OwnershipTrackerOpts {
     /** Check if a job is owned by the given agent (active or in grace window). */
     isJobOwnedByAgent: (agentId: string, jobId: string) => boolean;
     /**
-     * Optional DB-backed fallback. Returns `owned` when the orchestrator DB shows
-     * the (agent, job) pair as held by this coord OR a sibling coord — i.e.
-     * currently `dispatched`/`recovering` with the same `agent_id` /
-     * `recovery_agent_id`, or already terminal. `not-owned` is a decided refusal;
-     * `unknown` means the lookup itself could not be answered.
-     *
-     * When a Raft leader switch wipes the in-memory `agentJobs` Map on the
-     * replacement coord, this fallback accepts late frames from agents that are
-     * still draining instead of rejecting them as ownership violations.
+     * Optional DB-backed fallback: `owned` when the DB shows the (agent, job)
+     * pair held by this coord OR a sibling — `dispatched`/`recovering` with the
+     * same `agent_id` / `recovery_agent_id`, or already terminal. It accepts late
+     * frames from draining agents after a Raft leader switch wipes the in-memory
+     * `agentJobs` Map on the replacement coord.
      */
     isJobOwnedByAgentInDb?: (agentId: string, jobId: string) => Promise<OwnershipDbResult>;
     /**
      * Per-lookup deadline in ms, read fresh on every call so an operator can
-     * retune it fleet-wide without a restart. The read is itself bounded by
-     * {@link DEFAULT_OWNERSHIP_DB_CHECK_TIMEOUT_MS}, which is also the fallback
-     * when it stalls, throws, or returns a delay `setTimeout` cannot honour.
+     * retune it without a restart. Bounded and defaulted as `resolveTimeoutMs`
+     * describes.
      */
     getTimeoutMs?: () => Promise<number>;
-    /** Callback to disconnect an agent after escalation. */
     onDisconnect: (agentId: string, reason: string) => void;
     /** Number of violations before escalation (default: 5). */
     violationThreshold?: number;
@@ -60,75 +45,56 @@ export declare class OwnershipTracker {
     private readonly violationWindowMs;
     private readonly violations;
     /**
-     * L1 cache of `(agentId, jobId)` pairs proven by a positive DB
-     * fallback. Pre-empts a synchronous warn-and-reject for the very
-     * next chunk on the same pair, since `checkOwnership` is called
-     * once per inbound message and the local Map repopulation lags
-     * behind. The cache is intentionally small (per-agent capped) and
-     * is cleaned on agent disconnect via `cleanup(agentId)`.
+     * `(agentId, jobId)` pairs proven by a positive DB fallback, so the next
+     * per-message `checkOwnership` on the pair passes while the local Map
+     * repopulation lags. Per-agent capped; cleared by `cleanup(agentId)`.
      */
     private readonly dbAccepted;
     constructor(opts: OwnershipTrackerOpts);
     /**
-     * Synchronous ownership check. Returns true if ownership is valid
-     * per the in-memory dispatcher OR a previously-accepted DB fallback.
-     *
-     * Returns false WITHOUT recording a violation when a DB fallback is
-     * configured: the caller is expected to invoke `validateAsync` to
-     * confirm or reject the ownership before treating it as a real
-     * violation. This makes the writer idempotent across HA failover —
-     * a `log.chunk` arriving on the replacement coord doesn't get
-     * counted as a violation just because the local Map is empty.
+     * True when the in-memory dispatcher OR a previously-accepted DB fallback
+     * shows ownership. With a DB fallback configured, returns false WITHOUT
+     * recording a violation: the caller must run `validateAsync` to decide, so a
+     * `log.chunk` on an HA replacement coord with an empty local Map is not
+     * counted as a violation.
      */
     checkOwnership(agentId: string, jobId: string, messageType: string): boolean;
     /**
-     * Async fallback used by message handlers that want HA-safe
-     * acceptance of post-failover frames. Returns true if the DB shows
-     * the (agent, job) pair as currently or recently owned by any coord
-     * in the cluster. On `owned`, caches the result so subsequent
-     * same-pair frames return true synchronously via `checkOwnership`.
-     * On `not-owned`, records a violation exactly once (no recursive
-     * recordViolation from the synchronous call site — `checkOwnership`
-     * skipped it when the DB fallback was configured). On `unknown` the
-     * frame is refused without a violation: an unanswerable check is not
-     * evidence of misbehaviour, and treating it as such would let one
-     * database outage disconnect the whole fleet.
+     * HA-safe acceptance of post-failover frames: true when the DB shows the
+     * (agent, job) pair currently or recently owned by any coord. `owned` is
+     * cached so later same-pair frames pass `checkOwnership` synchronously.
+     * `not-owned` records the violation exactly once (`checkOwnership` skipped
+     * it). `unknown` refuses the frame without a violation (see
+     * {@link OwnershipDbResult}).
      */
     validateAsync(agentId: string, jobId: string, messageType: string): Promise<boolean>;
     /**
-     * Run the DB-backed lookup under a deadline. A query that throws or outruns
-     * the deadline resolves `unknown` — never `not-owned` — so a sick database
-     * refuses frames without accusing the agent of anything.
+     * DB lookup under a deadline. A query that throws or outruns it resolves
+     * `unknown`, never `not-owned`, so a sick database never accuses the agent.
      */
     private resolveFromDb;
     /**
-     * Resolve the deadline for one lookup, itself bounded by
-     * {@link DEFAULT_OWNERSHIP_DB_CHECK_TIMEOUT_MS}.
-     *
-     * The knob is stored in the same database the deadline exists to survive, so
-     * reading it unbounded would stall the very frame the deadline is there to
-     * refuse — the agent would wait out its own acknowledgment deadline instead
-     * of getting an answer. A read that stalls, throws, or yields a value
-     * `setTimeout` cannot honour (non-finite, sub-millisecond, or past
-     * {@link MAX_TIMER_DELAY_MS}) falls back to the compile-time default.
+     * The per-lookup deadline, its read bounded by
+     * {@link DEFAULT_OWNERSHIP_DB_CHECK_TIMEOUT_MS}: the knob lives in the same
+     * database the deadline exists to survive, and an unbounded read would make
+     * the agent wait out its own acknowledgment deadline. A read that stalls,
+     * throws, or yields a value `setTimeout` cannot honour (non-finite,
+     * sub-millisecond, or past {@link MAX_TIMER_DELAY_MS}) uses the default.
      */
     private resolveTimeoutMs;
     /**
-     * Cache a DB-proven (agent, job) pair so the next frame on the same pair
-     * short-circuits in `checkOwnership`. The per-agent set is capped (generously
-     * — a typical agent runs a handful of jobs) so a misbehaving agent cannot
-     * grow it without bound.
+     * The per-agent set is capped (generously — a typical agent runs a handful
+     * of jobs) so a misbehaving agent cannot grow it without bound.
      */
     private rememberDbAccepted;
     /**
-     * Record a violation for an agent. If threshold is exceeded within the
-     * violation window, triggers disconnect escalation.
+     * Record a violation for an agent. Reaching the threshold within the
+     * violation window triggers disconnect escalation.
      */
     private recordViolation;
     /**
-     * Clean up violation tracking AND the DB-accepted cache for a
-     * disconnected agent. Avoids cross-agent leakage when the same
-     * agent id is later reused.
+     * Clears violations AND the DB-accepted cache for a disconnected agent, so a
+     * reused agent id inherits nothing.
      */
     cleanup(agentId: string): void;
 }