@camstack/system 1.2.390 → 1.2.392

package/dist/builtins/storage-orchestrator/storage-migration-coordinator.d.ts

@@ -1,241 +1,241 @@
-import { RelocatableMediaCount, RelocatableMediaCountInput, RelocateFootageInput, RelocateJob, RelocateMediaInput, RelocateResidue, RelocateResidueInput, StorageMigrationDrainInput, StorageMigrationFootageMoveInput, StorageMigrationInput, StorageMigrationJob, StorageMigrationMediaMoveInput, StorageMigrationMover, StorageMigrationPlan, StorageMigrationResidue, UnstampedEventMediaCount } from '@camstack/types';
-import { StorageOrchestratorService } from './storage-orchestrator.service.js';
+import type { RelocatableMediaCount, RelocatableMediaCountInput, RelocateFootageInput, RelocateJob, RelocateMediaInput, RelocateResidue, RelocateResidueInput, StorageMigrationDrainInput, StorageMigrationFootageMoveInput, StorageMigrationInput, StorageMigrationJob, StorageMigrationMediaMoveInput, StorageMigrationMover, StorageMigrationPlan, StorageMigrationResidue, UnstampedEventMediaCount } from "@camstack/types";
+import type { StorageOrchestratorService } from "./storage-orchestrator.service.js";
 export interface MigrationState {
-    get(): Promise<StorageMigrationJob | null>;
-    set(value: StorageMigrationJob | null): Promise<void>;
+	get(): Promise<StorageMigrationJob | null>;
+	set(value: StorageMigrationJob | null): Promise<void>;
 }
 export interface MigrationHistoryState {
-    get(): Promise<readonly StorageMigrationJob[]>;
-    set(value: readonly StorageMigrationJob[]): Promise<void>;
+	get(): Promise<readonly StorageMigrationJob[]>;
+	set(value: readonly StorageMigrationJob[]): Promise<void>;
 }
 export interface LeaseParticipant {
-    pause(leaseId: string): Promise<void>;
-    resume(leaseId: string): Promise<void>;
+	pause(leaseId: string): Promise<void>;
+	resume(leaseId: string): Promise<void>;
 }
 export interface FootageMigrationParticipant extends LeaseParticipant {
-    startMove(input: StorageMigrationFootageMoveInput): Promise<{
-        jobId: string;
-    }>;
-    /**
-     * The SAME engine, armed without a maintenance lease — `recording.relocateFootage`.
-     * The `draining` phase runs after every writer has already been resumed, so
-     * there is no lease left to present; a lease-gated call there would be
-     * refused by the participant.
-     */
-    startDrain(input: RelocateFootageInput): Promise<{
-        jobId: string;
-    }>;
-    getMove(jobId: string): Promise<RelocateJob | null>;
-    cancelMove(jobId: string): Promise<boolean>;
-    refresh(leaseId: string): Promise<void>;
-    /** Every mover this engine knows about — including ones no migration armed. */
-    listMovers(): Promise<readonly RelocateJob[]>;
-    /** What a source STILL holds, from the durable hour ledger (D295). */
-    residue(input: RelocateResidueInput): Promise<RelocateResidue>;
+	startMove(input: StorageMigrationFootageMoveInput): Promise<{
+		jobId: string;
+	}>;
+	/**
+	* The SAME engine, armed without a maintenance lease — `recording.relocateFootage`.
+	* The `draining` phase runs after every writer has already been resumed, so
+	* there is no lease left to present; a lease-gated call there would be
+	* refused by the participant.
+	*/
+	startDrain(input: RelocateFootageInput): Promise<{
+		jobId: string;
+	}>;
+	getMove(jobId: string): Promise<RelocateJob | null>;
+	cancelMove(jobId: string): Promise<boolean>;
+	refresh(leaseId: string): Promise<void>;
+	/** Every mover this engine knows about — including ones no migration armed. */
+	listMovers(): Promise<readonly RelocateJob[]>;
+	/** What a source STILL holds, from the durable hour ledger (D295). */
+	residue(input: RelocateResidueInput): Promise<RelocateResidue>;
 }
 export interface MediaMigrationParticipant extends LeaseParticipant {
-    startMove(input: StorageMigrationMediaMoveInput): Promise<{
-        jobId: string;
-    }>;
-    /** Unleased twin of {@link startMove} — `pipelineAnalytics.relocateMedia`.
-     *  Also the only way to run the `seal` pass, which happens BEFORE any lease
-     *  exists. */
-    startDrain(input: RelocateMediaInput): Promise<{
-        jobId: string;
-    }>;
-    /** Rows that still carry no `locationId`. Read at plan time and re-read after
-     *  the seal; never inferred from a seal job's terminal state. */
-    countUnstamped(): Promise<UnstampedEventMediaCount>;
-    getMove(jobId: string): Promise<RelocateJob | null>;
-    cancelMove(jobId: string): Promise<boolean>;
-    refresh(leaseId: string): Promise<void>;
-    /** Every mover this engine knows about — including ones no migration armed. */
-    listMovers(): Promise<readonly RelocateJob[]>;
-    /** How many rows a pass would still act on — the media lane's residue, from
-     *  the same derivation that produces its `filesTotal`. */
-    residue(input: RelocatableMediaCountInput): Promise<RelocatableMediaCount>;
+	startMove(input: StorageMigrationMediaMoveInput): Promise<{
+		jobId: string;
+	}>;
+	/** Unleased twin of {@link startMove} — `pipelineAnalytics.relocateMedia`.
+	*  Also the only way to run the `seal` pass, which happens BEFORE any lease
+	*  exists. */
+	startDrain(input: RelocateMediaInput): Promise<{
+		jobId: string;
+	}>;
+	/** Rows that still carry no `locationId`. Read at plan time and re-read after
+	*  the seal; never inferred from a seal job's terminal state. */
+	countUnstamped(): Promise<UnstampedEventMediaCount>;
+	getMove(jobId: string): Promise<RelocateJob | null>;
+	cancelMove(jobId: string): Promise<boolean>;
+	refresh(leaseId: string): Promise<void>;
+	/** Every mover this engine knows about — including ones no migration armed. */
+	listMovers(): Promise<readonly RelocateJob[]>;
+	/** How many rows a pass would still act on — the media lane's residue, from
+	*  the same derivation that produces its `filesTotal`. */
+	residue(input: RelocatableMediaCountInput): Promise<RelocatableMediaCount>;
 }
 export interface StorageMigrationParticipants {
-    readonly pipeline: LeaseParticipant;
-    readonly recorder: FootageMigrationParticipant;
-    readonly analytics: MediaMigrationParticipant;
+	readonly pipeline: LeaseParticipant;
+	readonly recorder: FootageMigrationParticipant;
+	readonly analytics: MediaMigrationParticipant;
 }
 export interface StorageMigrationCoordinatorDeps {
-    readonly locations: StorageOrchestratorService;
-    readonly state: MigrationState;
-    readonly history?: MigrationHistoryState;
-    readonly participants: StorageMigrationParticipants;
-    readonly now: () => number;
-    readonly newId: () => string;
-    readonly sleep?: (ms: number) => Promise<void>;
-    readonly pollMs?: number;
-    /**
-     * A stable key for the PHYSICAL device behind a location — the orchestrator's
-     * own `getLocationDeviceKey`, injected so the planner does not reach for
-     * `fs` itself.
-     *
-     * `null` = not answerable here. It is PATH identity (a realpath), not
-     * `st_dev`: two distinct directories on one filesystem produce two different
-     * keys and are NOT detected as the same device. And a location can carry a
-     * `nodeId`, in which case the realpath would have to be taken on THAT node —
-     * so a remote location answers `null` rather than a meaningless local
-     * answer. Both limits are surfaced to the operator as plan findings; neither
-     * is papered over.
-     */
-    readonly deviceKeyOf?: (locationId: string) => Promise<string | null>;
+	readonly locations: StorageOrchestratorService;
+	readonly state: MigrationState;
+	readonly history?: MigrationHistoryState;
+	readonly participants: StorageMigrationParticipants;
+	readonly now: () => number;
+	readonly newId: () => string;
+	readonly sleep?: (ms: number) => Promise<void>;
+	readonly pollMs?: number;
+	/**
+	* A stable key for the PHYSICAL device behind a location — the orchestrator's
+	* own `getLocationDeviceKey`, injected so the planner does not reach for
+	* `fs` itself.
+	*
+	* `null` = not answerable here. It is PATH identity (a realpath), not
+	* `st_dev`: two distinct directories on one filesystem produce two different
+	* keys and are NOT detected as the same device. And a location can carry a
+	* `nodeId`, in which case the realpath would have to be taken on THAT node —
+	* so a remote location answers `null` rather than a meaningless local
+	* answer. Both limits are surfaced to the operator as plan findings; neither
+	* is papered over.
+	*/
+	readonly deviceKeyOf?: (locationId: string) => Promise<string | null>;
 }
 /**
- * Durable orchestration layer over the independent recorder and event-media
- * movers. It owns the only public migration state machine; participants expose
- * intentionally narrow lease/move primitives and never alter camera settings.
- */
+* Durable orchestration layer over the independent recorder and event-media
+* movers. It owns the only public migration state machine; participants expose
+* intentionally narrow lease/move primitives and never alter camera settings.
+*/
 export declare class StorageMigrationCoordinator {
-    private readonly deps;
-    private active;
-    private runPromise;
-    private startReserved;
-    constructor(deps: StorageMigrationCoordinatorDeps);
-    plan(input: StorageMigrationInput): Promise<StorageMigrationPlan>;
-    /** Same-device observations that are reported, not refused. */
-    private deviceFindings;
-    private deviceKey;
-    start(input: StorageMigrationInput): Promise<string>;
-    status(jobId?: string): Promise<StorageMigrationJob | null>;
-    /** Finished jobs, newest first, excluding the one `status` currently shows. */
-    history(): Promise<readonly StorageMigrationJob[]>;
-    cancel(jobId: string): Promise<boolean>;
-    /**
-     * Every mover running right now, in both lanes — including the ones no
-     * migration armed.
-     *
-     * `status` already carries a migration's own progress (the coordinator folds
-     * it onto each move from the poll it is already doing). This exists for the
-     * other half: `recording.relocateFootage` and `pipelineAnalytics.relocateMedia`
-     * are operator-callable, and until {@link drain} existed that was the only way
-     * to run a drain at all. Such a mover has no job to fold into, so without this
-     * read a five-hour operation is invisible in the UI.
-     *
-     * `migrationJobId` is best-effort by construction: the coordinator keeps ONE
-     * durable job, so a mover armed by an older, since-overwritten migration
-     * reports `null`. That is the honest answer — nothing here can still claim it.
-     */
-    movers(): Promise<readonly StorageMigrationMover[]>;
-    /**
-     * What every class's source STILL holds — the census behind a "drain
-     * remaining" action.
-     *
-     * A class appears here only when something is (or might be) left on a
-     * location outside its write set. An empty result therefore means exactly
-     * "there is nothing to drain", which is what lets the UI offer the action
-     * only when it is true, and what lets {@link drain} refuse rather than start
-     * a job that would move nothing and report `done` — the failure mode D295
-     * exists to end.
-     *
-     * `items: null` is "the archive could not be asked" and is still listed. A
-     * residue nobody could measure is the case an operator most needs to see;
-     * dropping it because the read failed would be the quiet success again.
-     */
-    residue(): Promise<readonly StorageMigrationResidue[]>;
-    /**
-     * Run the DRAIN half alone, against classes whose write set has already moved.
-     *
-     * ## Why this is a second verb rather than a looser `start`
-     *
-     * `start` refuses a destination that is already the class's only write target
-     * (`"recordingsLow:ssd" is already the only write target for "recordingsLow"`). That refusal
-     * is correct and it is load-bearing: there is genuinely nothing left to
-     * repoint, and an operator must never be able to re-repoint a migrated class
-     * by accident. Making `start` idempotent — "an already-repointed class
-     * proceeds straight to draining" — would delete that protection AND make the
-     * verb mean two different things depending on state, so the confirmation an
-     * operator reads ("pauses the writers…") would be a lie half the time.
-     *
-     * `drain` instead cannot repoint AT ALL: it never touches
-     * `setWriteTargets`, and its job starts in `draining` with `repointed`
-     * already true, so the `repointing` / `refreshing` / `resuming` blocks of
-     * {@link run} are behind it and unreachable. The two verbs are disjoint, and
-     * `start`'s refusal keeps meaning exactly what it meant.
-     *
-     * ## Why it re-derives the work instead of resuming the old job
-     *
-     * The finished job is the audit of what happened; re-opening it destroys
-     * that. And a drain is needed in cases where no migration job ever existed
-     * (a mover armed by hand, footage stranded on a location an operator added
-     * and then disabled again). One job = one operation, and the work list comes
-     * from {@link residue} — the archive — not from what a previous job believed.
-     */
-    drain(input: StorageMigrationDrainInput): Promise<string>;
-    /** Boot recovery resumes a durable unfinished state. A missing in-memory
-     * child mover is recreated from the same copy-if-absent input. */
-    recover(): Promise<void>;
-    /**
-     * The state machine. Both modes run the SAME phase handlers; only the order
-     * differs, which is the whole of the non-blocking design — no second mover,
-     * no parallel code path, nothing that can drift between the two.
-     *
-     *   blocking:    planning → pausing → moving → verifying → repointing →
-     *                refreshing → resuming → done
-     *   nonBlocking: planning → sealing → pausing → repointing → refreshing →
-     *                resuming → draining → verifying → done
-     *
-     * Written as a straight-line sequence of `if (phase === X)` blocks so boot
-     * recovery re-enters at whatever phase the durable record says, exactly as
-     * before.
-     */
-    private run;
-    private pauseParticipants;
-    private resumeParticipants;
-    private releaseAfterTerminal;
-    /**
-     * Start whatever is startable, honouring the ONE constraint the engines
-     * impose: each is single-flight.
-     *
-     * Two lanes — the recorder's footage engine and post-analysis's media engine
-     * — run in parallel with each other and strictly FIFO within themselves.
-     * `eventMedia` is the only class on the media lane.
-     */
-    private startOrResumeMoves;
-    private waitForMoves;
-    /**
-     * Nail every unstamped `eventMedia`/retrain row to the location its bytes are
-     * ALREADY on, before anything repoints. Runs with every writer up — it moves
-     * no bytes at all.
-     *
-     * The gate is the RE-COUNT, not the seal job's terminal state: a seal that
-     * failed some rows still finishes, and "finished" is not "there are none
-     * left". A remaining row here fails the job while nothing has been paused
-     * and nothing has been repointed, which is the cheapest possible place to
-     * discover it. So does a re-count that could not be TAKEN: the gate opens on
-     * a measured absence, and only on that.
-     *
-     * The seal's own mover job id is deliberately NOT durable. It is idempotent
-     * and cheap, so a coordinator restart mid-seal simply re-runs the whole
-     * phase — and the count that follows is what actually decides, so a lost job
-     * id cannot make the gate pass.
-     */
-    private sealEventMedia;
-    private waitForSeal;
-    private verifyMoves;
-    /**
-     * After a from→to copy whose source was NOT a write target: stop new writes
-     * to `from`. The rest of the write set is unchanged (that is the whole point
-     * of naming a source outside it). A location that is already disabled is
-     * left alone.
-     */
-    private freezeDrainedSources;
-    /**
-     * Arm one class's mover.
-     *
-     * `draining` runs after every writer has been resumed, so there is no lease
-     * left to present — it goes through the participants' UNLEASED entry points
-     * (`recording.relocateFootage` / `pipelineAnalytics.relocateMedia`), which
-     * are the same engines, not a second mover.
-     */
-    private startMove;
-    private moveStatus;
-    private cancelMove;
-    private participant;
-    private setPhase;
-    private finishCancelled;
-    private persist;
+	private readonly deps;
+	private active;
+	private runPromise;
+	private startReserved;
+	constructor(deps: StorageMigrationCoordinatorDeps);
+	plan(input: StorageMigrationInput): Promise<StorageMigrationPlan>;
+	/** Same-device observations that are reported, not refused. */
+	private deviceFindings;
+	private deviceKey;
+	start(input: StorageMigrationInput): Promise<string>;
+	status(jobId?: string): Promise<StorageMigrationJob | null>;
+	/** Finished jobs, newest first, excluding the one `status` currently shows. */
+	history(): Promise<readonly StorageMigrationJob[]>;
+	cancel(jobId: string): Promise<boolean>;
+	/**
+	* Every mover running right now, in both lanes — including the ones no
+	* migration armed.
+	*
+	* `status` already carries a migration's own progress (the coordinator folds
+	* it onto each move from the poll it is already doing). This exists for the
+	* other half: `recording.relocateFootage` and `pipelineAnalytics.relocateMedia`
+	* are operator-callable, and until {@link drain} existed that was the only way
+	* to run a drain at all. Such a mover has no job to fold into, so without this
+	* read a five-hour operation is invisible in the UI.
+	*
+	* `migrationJobId` is best-effort by construction: the coordinator keeps ONE
+	* durable job, so a mover armed by an older, since-overwritten migration
+	* reports `null`. That is the honest answer — nothing here can still claim it.
+	*/
+	movers(): Promise<readonly StorageMigrationMover[]>;
+	/**
+	* What every class's source STILL holds — the census behind a "drain
+	* remaining" action.
+	*
+	* A class appears here only when something is (or might be) left on a
+	* location outside its write set. An empty result therefore means exactly
+	* "there is nothing to drain", which is what lets the UI offer the action
+	* only when it is true, and what lets {@link drain} refuse rather than start
+	* a job that would move nothing and report `done` — the failure mode D295
+	* exists to end.
+	*
+	* `items: null` is "the archive could not be asked" and is still listed. A
+	* residue nobody could measure is the case an operator most needs to see;
+	* dropping it because the read failed would be the quiet success again.
+	*/
+	residue(): Promise<readonly StorageMigrationResidue[]>;
+	/**
+	* Run the DRAIN half alone, against classes whose write set has already moved.
+	*
+	* ## Why this is a second verb rather than a looser `start`
+	*
+	* `start` refuses a destination that is already the class's only write target
+	* (`"recordingsLow:ssd" is already the only write target for "recordingsLow"`). That refusal
+	* is correct and it is load-bearing: there is genuinely nothing left to
+	* repoint, and an operator must never be able to re-repoint a migrated class
+	* by accident. Making `start` idempotent — "an already-repointed class
+	* proceeds straight to draining" — would delete that protection AND make the
+	* verb mean two different things depending on state, so the confirmation an
+	* operator reads ("pauses the writers…") would be a lie half the time.
+	*
+	* `drain` instead cannot repoint AT ALL: it never touches
+	* `setWriteTargets`, and its job starts in `draining` with `repointed`
+	* already true, so the `repointing` / `refreshing` / `resuming` blocks of
+	* {@link run} are behind it and unreachable. The two verbs are disjoint, and
+	* `start`'s refusal keeps meaning exactly what it meant.
+	*
+	* ## Why it re-derives the work instead of resuming the old job
+	*
+	* The finished job is the audit of what happened; re-opening it destroys
+	* that. And a drain is needed in cases where no migration job ever existed
+	* (a mover armed by hand, footage stranded on a location an operator added
+	* and then disabled again). One job = one operation, and the work list comes
+	* from {@link residue} — the archive — not from what a previous job believed.
+	*/
+	drain(input: StorageMigrationDrainInput): Promise<string>;
+	/** Boot recovery resumes a durable unfinished state. A missing in-memory
+	* child mover is recreated from the same copy-if-absent input. */
+	recover(): Promise<void>;
+	/**
+	* The state machine. Both modes run the SAME phase handlers; only the order
+	* differs, which is the whole of the non-blocking design — no second mover,
+	* no parallel code path, nothing that can drift between the two.
+	*
+	*   blocking:    planning → pausing → moving → verifying → repointing →
+	*                refreshing → resuming → done
+	*   nonBlocking: planning → sealing → pausing → repointing → refreshing →
+	*                resuming → draining → verifying → done
+	*
+	* Written as a straight-line sequence of `if (phase === X)` blocks so boot
+	* recovery re-enters at whatever phase the durable record says, exactly as
+	* before.
+	*/
+	private run;
+	private pauseParticipants;
+	private resumeParticipants;
+	private releaseAfterTerminal;
+	/**
+	* Start whatever is startable, honouring the ONE constraint the engines
+	* impose: each is single-flight.
+	*
+	* Two lanes — the recorder's footage engine and post-analysis's media engine
+	* — run in parallel with each other and strictly FIFO within themselves.
+	* `eventMedia` is the only class on the media lane.
+	*/
+	private startOrResumeMoves;
+	private waitForMoves;
+	/**
+	* Nail every unstamped `eventMedia`/retrain row to the location its bytes are
+	* ALREADY on, before anything repoints. Runs with every writer up — it moves
+	* no bytes at all.
+	*
+	* The gate is the RE-COUNT, not the seal job's terminal state: a seal that
+	* failed some rows still finishes, and "finished" is not "there are none
+	* left". A remaining row here fails the job while nothing has been paused
+	* and nothing has been repointed, which is the cheapest possible place to
+	* discover it. So does a re-count that could not be TAKEN: the gate opens on
+	* a measured absence, and only on that.
+	*
+	* The seal's own mover job id is deliberately NOT durable. It is idempotent
+	* and cheap, so a coordinator restart mid-seal simply re-runs the whole
+	* phase — and the count that follows is what actually decides, so a lost job
+	* id cannot make the gate pass.
+	*/
+	private sealEventMedia;
+	private waitForSeal;
+	private verifyMoves;
+	/**
+	* After a from→to copy whose source was NOT a write target: stop new writes
+	* to `from`. The rest of the write set is unchanged (that is the whole point
+	* of naming a source outside it). A location that is already disabled is
+	* left alone.
+	*/
+	private freezeDrainedSources;
+	/**
+	* Arm one class's mover.
+	*
+	* `draining` runs after every writer has been resumed, so there is no lease
+	* left to present — it goes through the participants' UNLEASED entry points
+	* (`recording.relocateFootage` / `pipelineAnalytics.relocateMedia`), which
+	* are the same engines, not a second mover.
+	*/
+	private startMove;
+	private moveStatus;
+	private cancelMove;
+	private participant;
+	private setPhase;
+	private finishCancelled;
+	private persist;
 }