@massa-ai/core 1.2.1

package/dist/data/keyword/keyword-search-pg.js

@@ -0,0 +1,423 @@
+/**
+ * Keyword Search - PostgreSQL Implementation
+ *
+ * Uses PostgreSQL full-text search with to_tsvector for FTS capabilities.
+ */
+import { SearchSource } from "@massa-ai/shared";
+import { logger } from "@massa-ai/shared";
+import { getPgPool } from "../db-connection.js";
+import { installGuardOnTable } from "../../services/project-identity/identity-guard-installer.js";
+import { sanitizeTrigramQuery, levenshtein, maxEditDistance, } from "../../services/search/lexical-search.js";
+export class KeywordSearchPg {
+    pool = null;
+    poolPromise = null;
+    initialized = false;
+    initializationPromise = null;
+    trigramAvailable = false;
+    // Process-local LRU for fuzzyCorrect (parity with PostgreSQL store).
+    fuzzyCache = new Map();
+    static FUZZY_CACHE_SIZE = 512;
+    constructor() { }
+    async getPool() {
+        let pool = this.pool;
+        if (!pool) {
+            if (!this.poolPromise) {
+                this.poolPromise = getPgPool()
+                    .then((resolvedPool) => {
+                    this.pool = resolvedPool;
+                    return resolvedPool;
+                })
+                    .finally(() => {
+                    this.poolPromise = null;
+                });
+            }
+            pool = await this.poolPromise;
+        }
+        if (!this.initialized) {
+            if (!this.initializationPromise) {
+                this.initializationPromise = this.initTable(pool)
+                    .then(() => {
+                    this.initialized = true;
+                })
+                    .finally(() => {
+                    this.initializationPromise = null;
+                });
+            }
+            await this.initializationPromise;
+        }
+        return pool;
+    }
+    async initTable(pool) {
+        await pool.query(`
+      CREATE TABLE IF NOT EXISTS keyword_documents (
+        id TEXT PRIMARY KEY,
+        project_id TEXT NOT NULL,
+        content TEXT NOT NULL,
+        metadata JSONB DEFAULT '{}',
+        content_tsvector TSVECTOR,
+        created_at TIMESTAMPTZ DEFAULT NOW(),
+        updated_at TIMESTAMPTZ DEFAULT NOW()
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_keyword_project ON keyword_documents(project_id);
+      CREATE INDEX IF NOT EXISTS idx_keyword_content_tsvector ON keyword_documents USING GIN(content_tsvector);
+
+      CREATE OR REPLACE FUNCTION update_content_tsvector()
+      RETURNS TRIGGER AS $$
+      BEGIN
+        NEW.content_tsvector := to_tsvector('english', COALESCE(NEW.content, ''));
+        RETURN NEW;
+      END
+      $$ LANGUAGE plpgsql;
+
+      DROP TRIGGER IF EXISTS trigger_update_content_tsvector ON keyword_documents;
+      CREATE TRIGGER trigger_update_content_tsvector
+        BEFORE INSERT OR UPDATE ON keyword_documents
+        FOR EACH ROW
+        EXECUTE FUNCTION update_content_tsvector();
+
+      -- Vocabulary table for Levenshtein fuzzy correction (PG parity with PostgreSQL).
+      CREATE TABLE IF NOT EXISTS keyword_vocabulary (
+        word TEXT PRIMARY KEY
+      );
+    `);
+        // Project-identity guard (M16+M17 design: runtime-created tables install
+        // guards during initialization). Best-effort: sanitized code on failure,
+        // table init never aborts on a guard problem.
+        const guardCode = await installGuardOnTable(pool, "public", "keyword_documents", "project_id");
+        if (guardCode) {
+            logger.warn("[project-identity] guard install failed (sanitized)", {
+                table: "keyword_documents",
+                code: guardCode,
+            });
+        }
+        // pg_trgm extension for trigram similarity. Requires the extension to be
+        // available; on managed PG (RDS, etc.) this is usually pre-installed. On
+        // failure the trigram stream is disabled and RRF degrades to porter keyword.
+        try {
+            await pool.query(`CREATE EXTENSION IF NOT EXISTS pg_trgm`);
+            await pool.query(`
+        CREATE INDEX IF NOT EXISTS idx_keyword_content_trgm
+        ON keyword_documents USING GIN (content gin_trgm_ops);
+      `);
+            this.trigramAvailable = true;
+        }
+        catch (error) {
+            logger.warn('pg_trgm unavailable — trigram RRF stream disabled on PG', { err: error.message });
+            this.trigramAvailable = false;
+        }
+        logger.info('PostgreSQL keyword search initialized', {
+            trigram: this.trigramAvailable,
+        });
+    }
+    async add(id, content, metadata) {
+        const pool = await this.getPool();
+        const projectId = metadata?.projectId || 'default';
+        await pool.query(`INSERT INTO keyword_documents (id, project_id, content, metadata)
+       VALUES ($1, $2, $3, $4)
+       ON CONFLICT (id) DO UPDATE SET
+         content = EXCLUDED.content,
+         metadata = EXCLUDED.metadata,
+         updated_at = NOW()`, [id, projectId, content, JSON.stringify(metadata || {})]);
+        await this.populateVocabulary(pool, [content], id);
+    }
+    // Alias for compatibility
+    async index(id, content, metadata) {
+        await this.add(id, content, metadata);
+    }
+    async addBatch(documents) {
+        const pool = await this.getPool();
+        const client = await pool.connect();
+        try {
+            await client.query('BEGIN');
+            for (const doc of documents) {
+                const projectId = doc.metadata?.projectId || 'default';
+                await client.query(`INSERT INTO keyword_documents (id, project_id, content, metadata)
+           VALUES ($1, $2, $3, $4)
+           ON CONFLICT (id) DO UPDATE SET
+             content = EXCLUDED.content,
+             metadata = EXCLUDED.metadata,
+             updated_at = NOW()`, [doc.id, projectId, doc.content, JSON.stringify(doc.metadata || {})]);
+            }
+            await client.query('COMMIT');
+        }
+        catch (error) {
+            await client.query('ROLLBACK');
+            throw error;
+        }
+        finally {
+            client.release();
+        }
+        await this.populateVocabulary(pool, documents.map((document) => document.content), `batch:${documents.length}`);
+    }
+    /** Populate fuzzy vocabulary in bounded inserts; lexical indexing remains successful on failure. */
+    async populateVocabulary(pool, contents, source) {
+        try {
+            const vocabWords = new Set();
+            for (const content of contents) {
+                for (const token of content.split(/[^a-zA-Z0-9]+/)) {
+                    if (token.length < 3)
+                        continue;
+                    vocabWords.add(token.toLowerCase());
+                    for (const part of token.split(/(?<=[a-z])(?=[A-Z])/)) {
+                        if (part.length >= 3)
+                            vocabWords.add(part.toLowerCase());
+                    }
+                }
+            }
+            const words = [...vocabWords];
+            const INSERT_BATCH_SIZE = 5_000;
+            for (let offset = 0; offset < words.length; offset += INSERT_BATCH_SIZE) {
+                const batch = words.slice(offset, offset + INSERT_BATCH_SIZE);
+                const values = batch.map((_, index) => `($${index + 1})`).join(",");
+                await pool.query(`INSERT INTO keyword_vocabulary (word)
+           VALUES ${values}
+           ON CONFLICT (word) DO NOTHING`, batch);
+            }
+        }
+        catch (err) {
+            logger.debug('vocabulary population failed (non-fatal)', {
+                source,
+                err: err.message,
+            });
+        }
+    }
+    async search(query, projectIdOrLimit, limit = 10) {
+        const pool = await this.getPool();
+        const projectId = typeof projectIdOrLimit === 'string' ? projectIdOrLimit : undefined;
+        const resultLimit = typeof projectIdOrLimit === 'number' ? projectIdOrLimit : limit;
+        const searchTerms = query
+            .toLowerCase()
+            .split(/\s+/)
+            .map(t => t.replace(/[^a-z0-9_]/g, ''))
+            .filter(t => t.length > 2)
+            .map(t => `${t}:*`)
+            .join(' | ');
+        if (!searchTerms)
+            return [];
+        const queryText = projectId
+            ? `SELECT id, content, metadata,
+           ts_rank_cd(content_tsvector, to_tsquery('english', $1)) as rank
+         FROM keyword_documents
+         WHERE project_id = $2
+           AND content_tsvector @@ to_tsquery('english', $1)
+         ORDER BY rank DESC
+         LIMIT $3`
+            : `SELECT id, content, metadata,
+           ts_rank_cd(content_tsvector, to_tsquery('english', $1)) as rank
+         FROM keyword_documents
+         WHERE content_tsvector @@ to_tsquery('english', $1)
+         ORDER BY rank DESC
+         LIMIT $2`;
+        const params = projectId
+            ? [searchTerms, projectId, resultLimit]
+            : [searchTerms, resultLimit];
+        const { rows } = await pool.query(queryText, params);
+        return rows.map(row => ({
+            id: row.id,
+            content: row.content,
+            score: Math.min(1, parseFloat(row.rank) * 2),
+            source: SearchSource.KEYWORD,
+            metadata: row.metadata,
+        }));
+    }
+    async searchWithFilter(query, filters, limit = 10) {
+        const pool = await this.getPool();
+        const searchTerms = query
+            .toLowerCase()
+            .split(/\s+/)
+            .map(t => t.replace(/[^a-z0-9_]/g, ''))
+            .filter(t => t.length > 2)
+            .map(t => `${t}:*`)
+            .join(' | ');
+        if (!searchTerms)
+            return [];
+        const whereClauses = ["content_tsvector @@ to_tsquery('english', $1)"];
+        const params = [searchTerms];
+        let paramIndex = 2;
+        if (filters.projectId) {
+            whereClauses.push(`project_id = $${paramIndex}`);
+            params.push(filters.projectId);
+            paramIndex++;
+        }
+        if (filters.userId) {
+            whereClauses.push(`metadata->>'userId' = $${paramIndex}`);
+            params.push(filters.userId);
+            paramIndex++;
+        }
+        if (filters.sessionId) {
+            whereClauses.push(`metadata->>'sessionId' = $${paramIndex}`);
+            params.push(filters.sessionId);
+            paramIndex++;
+        }
+        if (filters.type) {
+            whereClauses.push(`metadata->>'type' = $${paramIndex}`);
+            params.push(filters.type);
+            paramIndex++;
+        }
+        params.push(limit);
+        const queryText = `
+      SELECT id, content, metadata,
+        ts_rank_cd(content_tsvector, to_tsquery('english', $1)) as rank
+      FROM keyword_documents
+      WHERE ${whereClauses.join(' AND ')}
+      ORDER BY rank DESC
+      LIMIT $${paramIndex}
+    `;
+        const { rows } = await pool.query(queryText, params);
+        return rows.map(row => ({
+            id: row.id,
+            content: row.content,
+            score: Math.min(1, parseFloat(row.rank) * 2),
+            source: SearchSource.KEYWORD,
+            metadata: row.metadata,
+        }));
+    }
+    /**
+     * Trigram similarity search using pg_trgm. Returns [] when pg_trgm is
+     * unavailable or the sanitized query is empty.
+     */
+    async searchTrigram(query, filters, limit = 10) {
+        if (!this.trigramAvailable)
+            return [];
+        const sanitized = sanitizeTrigramQuery(query, 'OR');
+        if (!sanitized)
+            return [];
+        const pool = await this.getPool();
+        // Match PostgreSQL's trigram OR semantics with exact case-insensitive
+        // substrings. PostgreSQL's `content % wholeQuery` compares a short query
+        // to the entire chunk and returned no rows for identifier substrings.
+        const trgmTerms = sanitized
+            .replace(/["']/g, "")
+            .split(/\s+(?:OR|AND)\s+/)
+            .map((term) => term.trim())
+            .filter(Boolean);
+        if (trgmTerms.length === 0)
+            return [];
+        try {
+            const text = filters.projectId
+                ? `SELECT id, content, metadata,
+                  (SELECT COUNT(*)::float / cardinality($1::text[])
+                   FROM unnest($1::text[]) AS term
+                   WHERE content ILIKE '%' || term || '%') AS sim
+           FROM keyword_documents
+           WHERE project_id = $2
+             AND EXISTS (
+               SELECT 1 FROM unnest($1::text[]) AS term
+               WHERE content ILIKE '%' || term || '%'
+             )
+           ORDER BY sim DESC
+           LIMIT $3`
+                : `SELECT id, content, metadata,
+                  (SELECT COUNT(*)::float / cardinality($1::text[])
+                   FROM unnest($1::text[]) AS term
+                   WHERE content ILIKE '%' || term || '%') AS sim
+           FROM keyword_documents
+           WHERE EXISTS (
+             SELECT 1 FROM unnest($1::text[]) AS term
+             WHERE content ILIKE '%' || term || '%'
+           )
+           ORDER BY sim DESC
+           LIMIT $2`;
+            const params = filters.projectId
+                ? [trgmTerms, filters.projectId, limit]
+                : [trgmTerms, limit];
+            const { rows } = await pool.query(text, params);
+            return rows.map((row) => ({
+                id: row.id,
+                content: row.content,
+                score: Math.min(1, parseFloat(row.sim) || 0),
+                source: SearchSource.KEYWORD,
+                metadata: row.metadata,
+            }));
+        }
+        catch (error) {
+            logger.debug('trigram search failed (non-fatal)', {
+                err: error.message,
+            });
+            return [];
+        }
+    }
+    /**
+     * Levenshtein fuzzy correction against keyword_vocabulary. Mirrors the
+     * PostgreSQL store's length-bounded, LRU-cached correction.
+     */
+    async fuzzyCorrect(word) {
+        const w = word.toLowerCase().trim();
+        if (w.length < 3)
+            return null;
+        if (this.fuzzyCache.has(w)) {
+            const cached = this.fuzzyCache.get(w) ?? null;
+            this.fuzzyCache.delete(w);
+            this.fuzzyCache.set(w, cached);
+            return cached;
+        }
+        const maxDist = maxEditDistance(w.length);
+        const pool = await this.getPool();
+        let rows = [];
+        try {
+            const res = await pool.query(`SELECT word FROM keyword_vocabulary
+         WHERE char_length(word) BETWEEN $1 AND $2`, [w.length - maxDist, w.length + maxDist]);
+            rows = res.rows;
+        }
+        catch (error) {
+            logger.debug('fuzzy vocab lookup failed (non-fatal)', {
+                err: error.message,
+            });
+            return null;
+        }
+        let bestWord = null;
+        let bestDist = maxDist + 1;
+        let exactMatch = false;
+        for (const { word: candidate } of rows) {
+            if (candidate === w) {
+                exactMatch = true;
+                break;
+            }
+            const dist = levenshtein(w, candidate);
+            if (dist < bestDist) {
+                bestDist = dist;
+                bestWord = candidate;
+            }
+        }
+        const result = exactMatch ? null : bestDist <= maxDist ? bestWord : null;
+        if (this.fuzzyCache.size >= KeywordSearchPg.FUZZY_CACHE_SIZE) {
+            const oldestKey = this.fuzzyCache.keys().next().value;
+            if (oldestKey !== undefined)
+                this.fuzzyCache.delete(oldestKey);
+        }
+        this.fuzzyCache.set(w, result);
+        return result;
+    }
+    async delete(id) {
+        const pool = await this.getPool();
+        const result = await pool.query('DELETE FROM keyword_documents WHERE id = $1', [id]);
+        return (result.rowCount ?? 0) > 0;
+    }
+    async update(id, content) {
+        const pool = await this.getPool();
+        await pool.query(`UPDATE keyword_documents
+       SET content = $1, updated_at = NOW()
+       WHERE id = $2`, [content, id]);
+    }
+    async deleteByProject(projectId) {
+        const pool = await this.getPool();
+        const result = await pool.query('DELETE FROM keyword_documents WHERE project_id = $1', [projectId]);
+        return result.rowCount ?? 0;
+    }
+    async clear() {
+        const pool = await this.getPool();
+        await pool.query('DELETE FROM keyword_documents');
+        logger.info('Keyword search cleared');
+    }
+    async close() {
+        if (this.pool) {
+            await this.pool.end();
+            this.pool = null;
+            this.poolPromise = null;
+            this.initialized = false;
+            this.initializationPromise = null;
+        }
+    }
+}
+//# sourceMappingURL=keyword-search-pg.js.map

package/dist/data/keyword/keyword-search-pg.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyword-search-pg.js","sourceRoot":"","sources":["../../../src/data/keyword/keyword-search-pg.ts"],"names":[],"mappings":"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"}

package/dist/data/managed-runs/managed-run-contract.d.ts

@@ -0,0 +1,193 @@
+/**
+ * Managed Run Contract — Wave 5 FR-08 / FR-09 / FR-20 / FR-26 / AD-W5-013 /
+ * AD-W5-014 / AD-W5-020.
+ *
+ * Public TypeScript contract for the {@link ManagedRunRepository}. B2/B3
+ * (and any downstream consumer) imports these interfaces verbatim — no
+ * re-implementation. Interface drift fails the batch per FR-26 / AC-28.
+ *
+ * The repository unifies an indexing lease (CAS acquire/heartbeat/release)
+ * with idempotent event_id dedup + FileCursor resume (FR-09 / FR-10). It
+ * mirrors the proven graph_generations lease pattern (Wave 3 MLTS-011) but
+ * is decoupled from the immutable snapshot row (AD-W5-004): an indexing run
+ * is a process-writer concept with a different lifecycle than a generation
+ * snapshot.
+ *
+ * Reaper contract (AD-W5-013): every {@link ManagedRunRepository.begin} call
+ * first issues
+ *   UPDATE managed_runs SET status='aborted'
+ *   WHERE project_id=? AND run_kind=? AND status='active'
+ *     AND lease_expires_at <= clock_timestamp()
+ * inside the same transaction as the subsequent INSERT, BEFORE attempting to
+ * acquire. Stale-but-active rows (orphaned by SIGKILL) are flipped to
+ * 'aborted' so the partial UNIQUE index `managed_runs_one_active_per_project_kind`
+ * (active rows only) stays satisfiable for the new row. Tested by AC-22.
+ *
+ * Race contract (AC-22): the INSERT uses `ON CONFLICT (project_id, run_kind)
+ * WHERE status='active' DO NOTHING` so a concurrent winner is observed as a
+ * clean no-op (0 rows returned) rather than a unique-violation
+ * statement-abort — Prisma's pg adapter cannot ROLLBACK TO SAVEPOINT
+ * transparently, so ON CONFLICT DO NOTHING keeps the transaction clean. The
+ * loser then SELECTs the winner's row to surface `busy` with the winner's
+ * runId. No 500, no `could not serialize access`.
+ *
+ * getActive pin (AD-W5-014): {@link ManagedRunRepository.getActive} filters
+ * by `status='active' AND lease_expires_at > clock_timestamp()
+ * ORDER BY lease_expires_at DESC LIMIT 1` exactly. A stale-but-active row
+ * must NOT be returned as "the active run" — the caller would see a live run
+ * that has already expired. Tested by AC-22.
+ */
+/** Run kind recognized by the `managed_runs.run_kind` CHECK constraint. */
+export type ManagedRunKind = "indexing" | "reindex" | "maintenance";
+/** Status values recognized by the `managed_runs.status` CHECK constraint. */
+export type ManagedRunStatus = "active" | "completed" | "failed" | "aborted";
+/**
+ * Resumable cursor persisted on `managed_runs.file_cursor` (FR-10).
+ * `path` is the relative project path of the next unprocessed file; `offset`
+ * is an opaque progress marker (file-size bytes already applied, for the
+ * common case where each file is a single event).
+ */
+export interface FileCursor {
+    path: string;
+    offset: number;
+}
+/** Lease token + expiry returned by a successful `begin()`. */
+export interface ManagedRunLease {
+    /** managed_runs.id (BigInt serial). */
+    runId: string;
+    projectId: string;
+    runKind: ManagedRunKind;
+    /** Random UUID token; required for heartbeat/complete/abort. */
+    leaseToken: string;
+    /** epoch ms — when the lease expires unless renewed. */
+    leaseExpiresAt: number;
+    /** The event_id this run was acquired under (FR-10 idempotency key). */
+    eventId: string;
+    /** Optional content_hash captured at acquire time. */
+    contentHash?: string;
+}
+export interface BeginManagedRunInput {
+    projectId: string;
+    runKind: ManagedRunKind;
+    /** FR-10 idempotency key (caller computes SHA-256(source_record || content_hash)). */
+    eventId: string;
+    /** Optional content_hash at acquire time. */
+    contentHash?: string;
+    /** Lease TTL in ms; 90s default matches FR-09. Bounded 1s..5min. */
+    leaseTtlMs?: number;
+}
+/**
+ * Outcome of {@link ManagedRunRepository.begin}.
+ *
+ * - `acquired`: this caller won the race; `lease` is valid.
+ * - `busy`: another live run holds the lease for this (projectId, runKind);
+ *   `activeRunId` is the existing run's id (for the 409 body); no 500.
+ */
+export type BeginManagedRunOutcome = {
+    status: "acquired";
+    lease: ManagedRunLease;
+} | {
+    status: "busy";
+    activeRunId: string;
+    leaseExpiresAt: number;
+};
+/** Outcome of {@link ManagedRunRepository.heartbeat}. */
+export type HeartbeatManagedRunOutcome = {
+    status: "renewed";
+    leaseExpiresAt: number;
+} | {
+    status: "lease_lost";
+};
+/** Outcome of {@link ManagedRunRepository.complete}. */
+export type CompleteManagedRunOutcome = {
+    status: "completed";
+    runId: string;
+} | {
+    status: "lease_lost";
+};
+/** Outcome of {@link ManagedRunRepository.abort}. */
+export type AbortManagedRunOutcome = {
+    status: "aborted";
+    runId: string;
+} | {
+    status: "lease_lost";
+};
+/**
+ * Snapshot of the live active run for a (projectId, runKind), or `null` when
+ * none exists. The filter is pinned per AD-W5-014:
+ *
+ *   SELECT * FROM managed_runs
+ *   WHERE project_id = $1 AND run_kind = $2
+ *     AND status = 'active'
+ *     AND lease_expires_at > clock_timestamp()
+ *   ORDER BY lease_expires_at DESC
+ *   LIMIT 1
+ *
+ * A stale-but-active row (lease_expires_at <= clock_timestamp()) is NOT
+ * returned; the caller must observe "no live run" rather than a row that
+ * looks live but is already expired. The reaper in begin() is responsible
+ * for flipping those rows to 'aborted' on the next acquire attempt.
+ */
+export interface ActiveManagedRun {
+    runId: string;
+    projectId: string;
+    runKind: ManagedRunKind;
+    eventId: string;
+    contentHash: string | null;
+    fileCursor: FileCursor | null;
+    leaseToken: string | null;
+    leaseExpiresAt: number;
+    heartbeatAt: number | null;
+    createdAt: number;
+}
+/**
+ * Repository contract for managed_runs (FR-08 / FR-09 / FR-20 / FR-26).
+ * Mirrors the CAS-lease shape of `GraphGenerationRepository` but decoupled
+ * from the immutable snapshot row (AD-W5-004).
+ *
+ * Implementation: `managed-run-repository-pg.ts`.
+ */
+export interface ManagedRunRepository {
+    /**
+     * Acquire a managed_runs lease for (projectId, runKind). Runs the reaper
+     * first (AD-W5-013): UPDATE expired active→aborted in the same transaction
+     * as the INSERT, so the partial UNIQUE on active rows stays satisfiable.
+     *
+     * Race contract (AC-22): two concurrent `begin()` calls on the same
+     * (projectId, runKind) — exactly one returns `acquired`, the other returns
+     * `busy` with the winner's runId. No 500, no `could not serialize access`.
+     */
+    begin(input: BeginManagedRunInput): Promise<BeginManagedRunOutcome>;
+    /**
+     * Renew the lease. Returns `lease_lost` when the token is unknown, the
+     * lease has already expired, or the run is no longer 'active'.
+     */
+    heartbeat(lease: ManagedRunLease, leaseTtlMs?: number): Promise<HeartbeatManagedRunOutcome>;
+    /**
+     * Mark the run `completed` and persist the final FileCursor. Idempotent
+     * re-acquire is not supported (a new event_id is required).
+     */
+    complete(lease: ManagedRunLease, fileCursor?: FileCursor): Promise<CompleteManagedRunOutcome>;
+    /**
+     * Persist an intermediate FileCursor mid-run (FR-10 resume). Called by the
+     * ETL load stage after each file-batch lands so a crash/restart resumes
+     * from the last committed file. Best-effort: a `lease_lost` outcome is
+     * logged but not thrown (the pipeline's heartbeat loop will abort the run
+     * separately). The cursor write happens AFTER the vector load commits
+     * (AD-W5-016) so kill-mid-load leaves the cursor at the previous file —
+     * restart re-processes the killed file (vectors upsert idempotently via
+     * deterministic doc ids).
+     */
+    updateFileCursor(lease: ManagedRunLease, fileCursor: FileCursor): Promise<HeartbeatManagedRunOutcome>;
+    /**
+     * Mark the run `failed` (status='aborted'). Used by the ETL pipeline's
+     * catch path on lease_lost or terminal error.
+     */
+    abort(lease: ManagedRunLease): Promise<AbortManagedRunOutcome>;
+    /**
+     * Pinned filter per AD-W5-014 (see {@link ActiveManagedRun}). Returns the
+     * one live active run, or `null` if none.
+     */
+    getActive(projectId: string, runKind: ManagedRunKind): Promise<ActiveManagedRun | null>;
+}
+//# sourceMappingURL=managed-run-contract.d.ts.map

package/dist/data/managed-runs/managed-run-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"managed-run-contract.d.ts","sourceRoot":"","sources":["../../../src/data/managed-runs/managed-run-contract.ts"],"names":[],"mappings":"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"}