velocious 1.0.575 → 1.0.577

package/build/src/deployment-api/run-store.d.ts

@@ -1,402 +0,0 @@
-/**
- * Marks a run as executing in this process so lease reconciliation never
- * reclaims it.
- * @param {string} id - Run id.
- * @returns {void} - No return value.
- */
-export function registerActiveDeploymentRun(id: string): void;
-/**
- * Removes a run from the in-process execution registry.
- * @param {string} id - Run id.
- * @returns {void} - No return value.
- */
-export function unregisterActiveDeploymentRun(id: string): void;
-/**
- * Persistence for deployment API runs and audit events. Owns its schema
- * lazily (the record-attachments store precedent) so the tables exist in the
- * consuming app's database without app-side migrations.
- */
-export default class DeploymentRunStore {
-    /**
-     * Runs constructor.
-     * @param {object} args - Options.
-     * @param {import("../configuration.js").default} args.configuration - Configuration instance.
-     * @param {string} [args.databaseIdentifier] - Database identifier; defaults to the primary database.
-     * @param {string} args.mountIdentifier - Stable identifier of the authenticated API mount.
-     * @param {number} [args.staleRunTimeoutMs] - Lease timeout after which an active run without a heartbeat counts as interrupted.
-     */
-    constructor({ configuration, databaseIdentifier, mountIdentifier, staleRunTimeoutMs }: {
-        configuration: import("../configuration.js").default;
-        databaseIdentifier?: string | undefined;
-        mountIdentifier: string;
-        staleRunTimeoutMs?: number | undefined;
-    });
-    configuration: import("../configuration.js").default;
-    databaseIdentifier: string;
-    mountIdentifier: string;
-    staleRunTimeoutMs: number;
-    /** @type {Promise<void> | null} */
-    _readyPromise: Promise<void> | null;
-    /**
-     * Ensures the run and audit tables exist.
-     * @returns {Promise<void>} - Resolves when the schema is ready.
-     */
-    ensureReady(): Promise<void>;
-    /**
-     * Finds a run by id.
-     * @param {string} id - Run id.
-     * @returns {Promise<DeploymentRunRow | null>} - The run or null.
-     */
-    findRunById(id: string): Promise<DeploymentRunRow | null>;
-    /**
-     * Finds a run by idempotency key.
-     * @param {string} idempotencyKey - Idempotency key.
-     * @returns {Promise<DeploymentRunRow | null>} - The run or null.
-     */
-    findRunByKey(idempotencyKey: string): Promise<DeploymentRunRow | null>;
-    /**
-     * Creates a run fenced by two advisory locks taken in a consistent global
-     * order — first the project/stage deployment lock, then the idempotency-key
-     * lock — so concurrent requests get a deterministic outcome instead of
-     * duplicate deployments or unique-constraint errors: an identical existing
-     * key replays, a different payload for an existing key conflicts, and an
-     * active run for the same project/stage blocks unless its ownership lease
-     * expired, in which case it is terminally reconciled as interrupted first.
-     * @param {object} args - Options.
-     * @param {string} args.idempotencyKey - Idempotency key.
-     * @param {string} args.project - Project identifier.
-     * @param {string} args.revision - Requested revision.
-     * @param {string} args.stage - Stage identifier.
-     * @returns {Promise<CreateRunOutcome>} - The outcome and the relevant run.
-     */
-    createRunIfPossible({ idempotencyKey, project, revision, stage }: {
-        idempotencyKey: string;
-        project: string;
-        revision: string;
-        stage: string;
-    }): Promise<CreateRunOutcome>;
-    /**
-     * Marks a run as running.
-     * @param {object} args - Options.
-     * @param {string} args.id - Run id.
-     * @param {number} args.startedAtMs - Start time in ms epoch.
-     * @returns {Promise<void>} - Resolves when updated.
-     */
-    markRunning({ id, startedAtMs }: {
-        id: string;
-        startedAtMs: number;
-    }): Promise<void>;
-    /**
-     * Renews the ownership lease of a run executing in this process. A no-op
-     * when the run already reached a terminal state.
-     * @param {object} args - Options.
-     * @param {string} args.id - Run id.
-     * @param {number} args.heartbeatAtMs - Heartbeat time in ms epoch.
-     * @returns {Promise<void>} - Resolves when updated.
-     */
-    heartbeat({ heartbeatAtMs, id }: {
-        id: string;
-        heartbeatAtMs: number;
-    }): Promise<void>;
-    /**
-     * Marks a run as succeeded with its sanitized result.
-     * @param {object} args - Options.
-     * @param {string} args.id - Run id.
-     * @param {string} args.ownerToken - Expected execution owner token.
-     * @param {number} args.finishedAtMs - Finish time in ms epoch.
-     * @param {?} args.result - Sanitized adapter report.
-     * @returns {Promise<void>} - Resolves when updated.
-     */
-    markSucceeded({ finishedAtMs, id, ownerToken, result }: {
-        id: string;
-        ownerToken: string;
-        finishedAtMs: number;
-        result: unknown;
-    }): Promise<void>;
-    /**
-     * Marks a run as failed with its sanitized failure payload.
-     * @param {object} args - Options.
-     * @param {string} args.id - Run id.
-     * @param {string} args.ownerToken - Expected execution owner token.
-     * @param {number} args.finishedAtMs - Finish time in ms epoch.
-     * @param {?} args.error - Sanitized failure payload.
-     * @returns {Promise<void>} - Resolves when updated.
-     */
-    markFailed({ error, finishedAtMs, id, ownerToken }: {
-        id: string;
-        ownerToken: string;
-        finishedAtMs: number;
-        error: unknown;
-    }): Promise<void>;
-    /**
-     * Fences a run after the adapter may have activated externally but its
-     * successful result could not be durably recorded. This state blocks future
-     * deployments until an operator reconciles the external outcome.
-     * @param {object} args - Options.
-     * @param {string} args.id - Run id.
-     * @param {string} args.ownerToken - Expected execution owner token.
-     * @param {number} args.finishedAtMs - Time reconciliation became necessary in ms epoch.
-     * @param {?} args.error - Sanitized operator-facing explanation.
-     * @returns {Promise<void>} - Resolves when updated.
-     */
-    markReconciliationRequired({ error, finishedAtMs, id, ownerToken }: {
-        id: string;
-        ownerToken: string;
-        finishedAtMs: number;
-        error: unknown;
-    }): Promise<void>;
-    /**
-     * Records a sanitized audit event.
-     * @param {object} args - Options.
-     * @param {string} args.event - Event name.
-     * @param {?} args.payload - Sanitized payload.
-     * @param {string | null} args.runId - Owning run id.
-     * @returns {Promise<void>} - Resolves when recorded.
-     */
-    addAuditEvent({ event, payload, runId }: {
-        event: string;
-        payload: unknown;
-        runId: string | null;
-    }): Promise<void>;
-    /**
-     * Lists audit events for a run in creation order.
-     * @param {object} args - Options.
-     * @param {string} args.runId - Run id.
-     * @returns {Promise<DeploymentAuditEventRow[]>} - Audit events.
-     */
-    listAuditEvents({ runId }: {
-        runId: string;
-    }): Promise<DeploymentAuditEventRow[]>;
-    /**
-     * Builds the advisory-lock name for a project/stage pair. Hashed so the name
-     * stays within driver limits (MySQL/MariaDB cap lock names at 64 chars)
-     * regardless of identifier length.
-     * @param {object} args - Options.
-     * @param {string} args.project - Project identifier.
-     * @param {string} args.stage - Stage identifier.
-     * @returns {string} - Bounded advisory-lock name.
-     */
-    _deploymentLockName({ project, stage }: {
-        project: string;
-        stage: string;
-    }): string;
-    /**
-     * Builds the advisory-lock name serializing one idempotency key within this mount.
-     * @param {string} idempotencyKey - Idempotency key.
-     * @returns {string} - Bounded advisory-lock name.
-     */
-    _idempotencyLockName(idempotencyKey: string): string;
-    /**
-     * Decides whether an active run counts as interrupted: its owner lease
-     * (heartbeat, or the request time when it never started) is older than the
-     * configured timeout and it is not executing in this process. A run with a
-     * fresh lease owned by another worker is genuinely active and must never be
-     * reclaimed here.
-     * @param {DeploymentRunRow} run - Active run.
-     * @returns {boolean} - Whether the run is interrupted.
-     */
-    _isRunInterrupted(run: DeploymentRunRow): boolean;
-    /**
-     * Reconciles an expired ownership lease. Pending work is safely interrupted
-     * because external activation never began. Running work requires operator
-     * reconciliation because the external outcome may already have changed.
-     * Runs inside the project/stage deployment lock, so exactly one reconciler
-     * wins.
-     * @param {import("../database/drivers/base.js").default} db - Database connection.
-     * @param {DeploymentRunRow} run - Interrupted run.
-     * @returns {Promise<void>} - Resolves when reconciled.
-     */
-    _reconcileExpiredRun(db: import("../database/drivers/base.js").default, run: DeploymentRunRow): Promise<void>;
-    /**
-     * Adds the ownership lease columns to a runs table created before they
-     * existed (the background-jobs store column-upgrade precedent).
-     * @param {import("../database/drivers/base.js").default} db - Database connection.
-     * @returns {Promise<void>} - Resolves when the columns exist.
-     */
-    _ensureRunColumns(db: import("../database/drivers/base.js").default): Promise<void>;
-    /**
-     * Adds and safely backfills a mount identifier on an existing lazily-owned table.
-     * Legacy rows were not attributable to an authenticated mount, so they are
-     * quarantined in an unreachable scope instead of being exposed to whichever
-     * mount happens to initialize first.
-     * @param {import("../database/drivers/base.js").default} db - Database connection.
-     * @param {string} tableName - Lazily-owned table name.
-     * @returns {Promise<void>} - Resolves when the column exists.
-     */
-    _ensureMountIdentifierColumn(db: import("../database/drivers/base.js").default, tableName: string): Promise<void>;
-    /**
-     * Assigns pre-scope rows to a reserved identifier no real mount can use.
-     * @param {import("../database/drivers/base.js").default} db - Database connection.
-     * @param {string} tableName - Table containing legacy rows.
-     * @returns {Promise<void>} - Resolves when legacy rows are quarantined.
-     */
-    _quarantineLegacyRows(db: import("../database/drivers/base.js").default, tableName: string): Promise<void>;
-    /**
-     * Replaces the legacy global idempotency-key uniqueness with mount-scoped
-     * uniqueness. The scoped index is created before the old one is removed, so
-     * an interrupted lazy upgrade never leaves idempotency keys unfenced.
-     * @param {import("../database/drivers/base.js").default} db - Database connection.
-     * @returns {Promise<void>} - Resolves when index ownership is scoped.
-     */
-    _ensureScopedIdempotencyIndex(db: import("../database/drivers/base.js").default): Promise<void>;
-    /**
-     * Applies a terminal transition only while the expected execution owner
-     * still owns a running row. A stale worker therefore cannot overwrite a
-     * state already written by lease reconciliation.
-     * @param {object} args - Options.
-     * @param {Record<string, ?>} args.data - Terminal column values.
-     * @param {string} args.id - Run id.
-     * @param {string} args.ownerToken - Expected execution owner token.
-     * @returns {Promise<void>} - Resolves when updated.
-     */
-    _transitionRunningRun({ data, id, ownerToken }: {
-        data: Record<string, unknown>;
-        id: string;
-        ownerToken: string;
-    }): Promise<void>;
-    /**
-     * Finds a run by id on an open connection.
-     * @param {import("../database/drivers/base.js").default} db - Database connection.
-     * @param {string} id - Run id.
-     * @returns {Promise<DeploymentRunRow | null>} - The run or null.
-     */
-    _findRunById(db: import("../database/drivers/base.js").default, id: string): Promise<DeploymentRunRow | null>;
-    /**
-     * Finds a run by idempotency key on an open connection.
-     * @param {import("../database/drivers/base.js").default} db - Database connection.
-     * @param {string} idempotencyKey - Idempotency key.
-     * @returns {Promise<DeploymentRunRow | null>} - The run or null.
-     */
-    _findRunByKey(db: import("../database/drivers/base.js").default, idempotencyKey: string): Promise<DeploymentRunRow | null>;
-    /**
-     * Finds the run blocking another deployment for a project/stage.
-     * @param {import("../database/drivers/base.js").default} db - Database connection.
-     * @param {object} args - Options.
-     * @param {string} args.project - Project identifier.
-     * @param {string} args.stage - Stage identifier.
-     * @returns {Promise<DeploymentRunRow | null>} - The blocking run or null.
-     */
-    _findBlockingRun(db: import("../database/drivers/base.js").default, { project, stage }: {
-        project: string;
-        stage: string;
-    }): Promise<DeploymentRunRow | null>;
-    /**
-     * Normalizes a raw run row.
-     * @param {?} row - Raw database row.
-     * @returns {DeploymentRunRow} - Normalized run row.
-     */
-    _runRowFromDb(row: unknown): DeploymentRunRow;
-    /**
-     * Normalizes a raw audit event row.
-     * @param {?} row - Raw database row.
-     * @returns {DeploymentAuditEventRow} - Normalized audit event row.
-     */
-    _auditRowFromDb(row: unknown): DeploymentAuditEventRow;
-    /**
-     * Runs a callback with a pooled connection.
-     * @template T
-     * @param {(db: import("../database/drivers/base.js").default) => Promise<T>} callback - Callback.
-     * @returns {Promise<T>} - Callback result.
-     */
-    _withDb<T>(callback: (db: import("../database/drivers/base.js").default) => Promise<T>): Promise<T>;
-}
-/**
- * DeploymentRunRow type.
- */
-export type DeploymentRunRow = {
-    /**
-     * - Run id (UUID).
-     */
-    id: string;
-    /**
-     * - Stable identifier of the authenticated API mount that owns the run.
-     */
-    mountIdentifier: string;
-    /**
-     * - Allowlisted project identifier.
-     */
-    project: string;
-    /**
-     * - Allowlisted stage identifier.
-     */
-    stage: string;
-    /**
-     * - Full immutable requested Git revision.
-     */
-    revision: string;
-    /**
-     * - Caller-supplied idempotency key.
-     */
-    idempotencyKey: string;
-    /**
-     * - Run status: pending, running, succeeded, failed, interrupted, or reconciliation_required.
-     */
-    status: string;
-    /**
-     * - Sanitized adapter report, or null while unset.
-     */
-    result: unknown;
-    /**
-     * - Sanitized failure payload, or null while unset.
-     */
-    error: unknown;
-    /**
-     * - Creation time in ms epoch.
-     */
-    requestedAtMs: number;
-    /**
-     * - Execution start in ms epoch.
-     */
-    startedAtMs: number | null;
-    /**
-     * - Terminal time in ms epoch.
-     */
-    finishedAtMs: number | null;
-    /**
-     * - Ownership token of the executing process.
-     */
-    ownerToken: string | null;
-    /**
-     * - Last ownership lease heartbeat in ms epoch.
-     */
-    heartbeatAtMs: number | null;
-};
-/**
- * DeploymentAuditEventRow type.
- */
-export type DeploymentAuditEventRow = {
-    /**
-     * - Event id (UUID).
-     */
-    id: string;
-    /**
-     * - Owning run id.
-     */
-    runId: string | null;
-    /**
-     * - Event name (e.g. run_requested, run_started, run_succeeded, run_failed).
-     */
-    event: string;
-    /**
-     * - Sanitized JSON payload.
-     */
-    payload: unknown;
-    /**
-     * - Creation time in ms epoch.
-     */
-    createdAtMs: number;
-};
-/**
- * CreateRunOutcome type.
- */
-export type CreateRunOutcome = {
-    /**
-     * - What happened.
-     */
-    outcome: "created" | "replay" | "conflict" | "in_progress" | "reconciliation_required";
-    /**
-     * - The created, replayed, conflicting, or active run; null when the deployment lock was held mid-creation by another process.
-     */
-    run: DeploymentRunRow | null;
-};
-//# sourceMappingURL=run-store.d.ts.map

package/build/src/deployment-api/run-store.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"run-store.d.ts","sourceRoot":"","sources":["../../../src/deployment-api/run-store.js"],"names":[],"mappings":"AA8DA;;;;;GAKG;AACH,gDAHW,MAAM,GACJ,IAAI,CAIhB;AAED;;;;GAIG;AACH,kDAHW,MAAM,GACJ,IAAI,CAIhB;AAaD;;;;GAIG;AACH;IACE;;;;;;;OAOG;IACH,uFALG;QAAoD,aAAa,EAAzD,OAAO,qBAAqB,EAAE,OAAO;QACvB,kBAAkB;QACnB,eAAe,EAA5B,MAAM;QACQ,iBAAiB;KACzC,EAYA;IANC,qDAAkC;IAClC,2BAAyD;IACzD,wBAAsC;IACtC,0BAA0C;IAC1C,mCAAmC;IACnC,eADW,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CACN;IAG3B;;;OAGG;IACH,eAFa,OAAO,CAAC,IAAI,CAAC,CAoEzB;IAED;;;;OAIG;IACH,gBAHW,MAAM,GACJ,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAM5C;IAED;;;;OAIG;IACH,6BAHW,MAAM,GACJ,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAM5C;IAED;;;;;;;;;;;;;;OAcG;IACH,kEANG;QAAqB,cAAc,EAA3B,MAAM;QACO,OAAO,EAApB,MAAM;QACO,QAAQ,EAArB,MAAM;QACO,KAAK,EAAlB,MAAM;KACd,GAAU,OAAO,CAAC,gBAAgB,CAAC,CAuFrC;IAED;;;;;;OAMG;IACH,iCAJG;QAAqB,EAAE,EAAf,MAAM;QACO,WAAW,EAAxB,MAAM;KACd,GAAU,OAAO,CAAC,IAAI,CAAC,CAoBzB;IAED;;;;;;;OAOG;IACH,iCAJG;QAAqB,EAAE,EAAf,MAAM;QACO,aAAa,EAA1B,MAAM;KACd,GAAU,OAAO,CAAC,IAAI,CAAC,CAWzB;IAED;;;;;;;;OAQG;IACH,wDANG;QAAqB,EAAE,EAAf,MAAM;QACO,UAAU,EAAvB,MAAM;QACO,YAAY,EAAzB,MAAM;QACE,MAAM,EAAd,OAAC;KACT,GAAU,OAAO,CAAC,IAAI,CAAC,CAQzB;IAED;;;;;;;;OAQG;IACH,oDANG;QAAqB,EAAE,EAAf,MAAM;QACO,UAAU,EAAvB,MAAM;QACO,YAAY,EAAzB,MAAM;QACE,KAAK,EAAb,OAAC;KACT,GAAU,OAAO,CAAC,IAAI,CAAC,CAQzB;IAED;;;;;;;;;;OAUG;IACH,oEANG;QAAqB,EAAE,EAAf,MAAM;QACO,UAAU,EAAvB,MAAM;QACO,YAAY,EAAzB,MAAM;QACE,KAAK,EAAb,OAAC;KACT,GAAU,OAAO,CAAC,IAAI,CAAC,CAQzB;IAED;;;;;;;OAOG;IACH,yCALG;QAAqB,KAAK,EAAlB,MAAM;QACE,OAAO,EAAf,OAAC;QACmB,KAAK,EAAzB,MAAM,GAAG,IAAI;KACrB,GAAU,OAAO,CAAC,IAAI,CAAC,CAiBzB;IAED;;;;;OAKG;IACH,2BAHG;QAAqB,KAAK,EAAlB,MAAM;KACd,GAAU,OAAO,CAAC,uBAAuB,EAAE,CAAC,CAe9C;IAED;;;;;;;;OAQG;IACH,wCAJG;QAAqB,OAAO,EAApB,MAAM;QACO,KAAK,EAAlB,MAAM;KACd,GAAU,MAAM,CAMlB;IAED;;;;OAIG;IACH,qCAHW,MAAM,GACJ,MAAM,CAMlB;IAED;;;;;;;;OAQG;IACH,uBAHW,gBAAgB,GACd,OAAO,CAQnB;IAED;;;;;;;;;OASG;IACH,yBAJW,OAAO,6BAA6B,EAAE,OAAO,OAC7C,gBAAgB,GACd,OAAO,CAAC,IAAI,CAAC,CAgCzB;IAED;;;;;OAKG;IACH,sBAHW,OAAO,6BAA6B,EAAE,OAAO,GAC3C,OAAO,CAAC,IAAI,CAAC,CAyBzB;IAED;;;;;;;;OAQG;IACH,iCAJW,OAAO,6BAA6B,EAAE,OAAO,aAC7C,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAgBzB;IAED;;;;;OAKG;IACH,0BAJW,OAAO,6BAA6B,EAAE,OAAO,aAC7C,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAQzB;IAED;;;;;;OAMG;IACH,kCAHW,OAAO,6BAA6B,EAAE,OAAO,GAC3C,OAAO,CAAC,IAAI,CAAC,CAoCzB;IAED;;;;;;;;;OASG;IACH,gDALG;QAAgC,IAAI,EAA5B,MAAM,CAAC,MAAM,EAAE,OAAC,CAAC;QACJ,EAAE,EAAf,MAAM;QACO,UAAU,EAAvB,MAAM;KACd,GAAU,OAAO,CAAC,IAAI,CAAC,CAezB;IAED;;;;;OAKG;IACH,iBAJW,OAAO,6BAA6B,EAAE,OAAO,MAC7C,MAAM,GACJ,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAW5C;IAED;;;;;OAKG;IACH,kBAJW,OAAO,6BAA6B,EAAE,OAAO,kBAC7C,MAAM,GACJ,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAW5C;IAED;;;;;;;OAOG;IACH,qBANW,OAAO,6BAA6B,EAAE,OAAO,sBAErD;QAAqB,OAAO,EAApB,MAAM;QACO,KAAK,EAAlB,MAAM;KACd,GAAU,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAY5C;IAED;;;;OAIG;IACH,mBAHW,OAAC,GACC,gBAAgB,CAqB5B;IAED;;;;OAIG;IACH,qBAHW,OAAC,GACC,uBAAuB,CAYnC;IAED;;;;;OAKG;IACH,QAJa,CAAC,YACH,CAAC,EAAE,EAAE,OAAO,6BAA6B,EAAE,OAAO,KAAK,OAAO,CAAC,CAAC,CAAC,GAC/D,OAAO,CAAC,CAAC,CAAC,CAYtB;CACF;;;;;;;;QApxBa,MAAM;;;;qBACN,MAAM;;;;aACN,MAAM;;;;WACN,MAAM;;;;cACN,MAAM;;;;oBACN,MAAM;;;;YACN,MAAM;;;;YACN,OAAC;;;;WACD,OAAC;;;;mBACD,MAAM;;;;iBACN,MAAM,GAAG,IAAI;;;;kBACb,MAAM,GAAG,IAAI;;;;gBACb,MAAM,GAAG,IAAI;;;;mBACb,MAAM,GAAG,IAAI;;;;;;;;;QAKb,MAAM;;;;WACN,MAAM,GAAG,IAAI;;;;WACb,MAAM;;;;aACN,OAAC;;;;iBACD,MAAM;;;;;;;;;aAKN,SAAS,GAAG,QAAQ,GAAG,UAAU,GAAG,aAAa,GAAG,yBAAyB;;;;SAC7E,gBAAgB,GAAG,IAAI"}