import { type OxigraphBinaryLocations } from './oxigraph-binary.js'; import type { IdentityState, OxigraphOwnerRecordRead, OxigraphOwnerRecordV1 } from './oxigraph-owner-record.js'; import type { ProcessInstance } from './process-probe.js'; /** * Exactly one binary, for a caller without resolved binary locations: no * directory is taken for the managed cache unless the binary module says so. */ export declare function oxigraphBinaryCatalog(path: string): OxigraphBinaryLocations; /** `catalog` plus one more exact binary (a recorded binary, say). */ export declare function withOxigraphBinary(catalog: OxigraphBinaryLocations, path: string): OxigraphBinaryLocations; /** Whether `executable` is one of the catalog's Oxigraph binaries. */ export declare function isCatalogedOxigraph(catalog: OxigraphBinaryLocations, executable: string): boolean; /** * Whether a process runs a known Oxigraph binary with this store's * arguments: the binary must be the executable (argv[0]), or the script * right after a known interpreter, followed by `serve --location `. * A catalogued path that merely appears among another program's arguments * does not count. Exact argv (from `/proc`) is compared token by token. * Where only `ps` display text exists, argv boundaries are lost, so the text * is compared only when neither the store path nor a known binary path * contains whitespace; otherwise the answer is `ambiguous`. */ export declare function matchManagedOxigraphStore(holder: Pick, location: string, binaries: OxigraphBinaryLocations): 'match' | 'no-match' | 'ambiguous'; /** * Who owns the store now. `unknown` (a record that could not be read, or a * recorded owner whose state could not be read) leaves every holder running. */ export type Ownership = { kind: 'unrecorded'; } | { kind: 'unknown'; reason: string; } | { kind: 'owners-live'; record: OxigraphOwnerRecordV1; } | { kind: 'owner-gone'; record: OxigraphOwnerRecordV1; gone: { role: 'daemon' | 'launcher'; pid: number; }; }; /** Whether the recorded daemon and launcher still run; checked for a v1 record only. */ export interface RecordedOwnerStates { daemon: IdentityState; launcher: IdentityState; } /** * Ownership from the record, the states of its daemon and launcher, and the * current boot (null when it could not be read). One confirmed exit is enough * to call the owner gone; otherwise an owner whose state could not be read * makes the ownership unknown. A malformed record is ignored, as if there * were none; an unreadable one is not. A record from an earlier boot is * ignored too: its PIDs and start times may name unrelated processes now, so * only the command and parent rules apply. When the current boot cannot be * read, a record cannot be matched to it, and the ownership is unknown. */ export declare function deriveOwnership(read: OxigraphOwnerRecordRead, states: RecordedOwnerStates | null, currentBoot: string | null): Ownership; export type StopReason = { kind: 'owner-gone'; role: 'daemon' | 'launcher'; pid: number; } | { kind: 'reparented-to-init'; } | { kind: 'parent-exited'; ppid: number; }; export type LeaveReason = { kind: 'owners-live'; daemonPid: number; launcherPid: number; } | { kind: 'ownership-unknown'; reason: string; } | { kind: 'parent-unknown'; ppid: number; reason: string; } | { kind: 'not-this-store'; } | { kind: 'argv-ambiguous'; } | { kind: 'parent-alive'; ppid: number; parentCommand: string; recorded: boolean; }; export type HolderDecision = { action: 'stop'; reason: StopReason; } | { action: 'leave'; reason: LeaveReason; }; export declare function describeStop(reason: StopReason): string; export declare function describeLeave(reason: LeaveReason): string; /** * Why a holder the reaper left running may still be this node's Oxigraph * holding the store: judged and left for another reason than not being it, * its signal refused, or it could not be re-checked or inspected. */ export type HolderBlock = { kind: 'left'; reason: Exclude; } | { kind: 'signal-refused'; } | { kind: 'unconfirmed'; reason: string; } | { kind: 'uninspectable'; reason: string; }; /** * Why the store may still be held by this node's Oxigraph after a reclaim. * Nothing may be launched over it: the launch would fail on the lock, and * recording it would replace the owner record a later reclaim needs. */ export type StoreHold = { kind: 'holders-unlisted'; } | { kind: 'holders-left'; holders: ReadonlyArray<{ pid: number; block: HolderBlock; }>; } | { kind: 'not-confirmed-gone'; pids: readonly number[]; }; /** * What a holder left for `reason` means for a launch: only one that is not * this node's Oxigraph for this store (a backup tool reading LOCK, say) * leaves the store free. */ export declare function leaveBlock(reason: LeaveReason): HolderBlock | null; export declare function describeHolderBlock(block: HolderBlock): string; export declare function describeStoreHold(hold: StoreHold): string; export declare const MAX_LAUNCHER_DEPTH = 4; /** One lock holder as observed: the holder and its ancestors, nearest first. */ export interface HolderObservation { holder: ProcessInstance; /** * The holder's parent, its parent and so on, up to MAX_LAUNCHER_DEPTH, * stopping before PID 1. */ ancestors: readonly ProcessInstance[]; /** * Why the walk stopped: it reached PID 1 or MAX_LAUNCHER_DEPTH * (`complete`), the next ancestor has exited (`gone`), or the next * ancestor could not be read (`unknown`). */ ancestryEnd: { state: 'complete'; } | { state: 'gone'; } | { state: 'unknown'; reason: string; }; } export declare function classifyHolder({ holder, ancestors, ancestryEnd }: HolderObservation, ctx: { location: string; ownership: Ownership; binaries: OxigraphBinaryLocations; }): HolderDecision; //# sourceMappingURL=oxigraph-reclaim-policy.d.ts.map