ghagga-db 3.3.0 → 3.5.0

package/dist/queries.js

@@ -1,6 +1,6 @@
 import { createHash } from 'node:crypto';
-import { and, asc, desc, eq, gt, inArray, or, sql } from 'drizzle-orm';
-import { DEFAULT_REPO_SETTINGS, githubUserMappings, installationSettings, installations, memoryObservations, memorySessions, repositories, reviews, } from './schema.js';
+import { and, asc, desc, eq, gt, inArray, isNotNull, isNull, lt, or, sql, } from 'drizzle-orm';
+import { DEFAULT_REPO_SETTINGS, explanationInvocations, githubUserMappings, installationSettings, installations, issueDrafts, memoryObservations, memorySessions, repositories, reviews, } from './schema.js';
 // ─── Installations ──────────────────────────────────────────────
 export async function upsertInstallation(db, data) {
     const existing = await db
@@ -106,13 +106,20 @@ export async function getInstallationById(db, installationId) {
         .limit(1);
     return row ?? null;
 }
+function resolveEffectiveRepoSettings(settings) {
+    const selectedSettings = (settings ?? DEFAULT_REPO_SETTINGS);
+    return {
+        ...selectedSettings,
+        explanationsEnabled: selectedSettings.explanationsEnabled ?? false,
+    };
+}
 export async function getEffectiveRepoSettings(db, repo) {
     if (!repo.useGlobalSettings) {
         return {
             providerChain: (repo.providerChain ?? []),
             aiReviewEnabled: repo.aiReviewEnabled,
             reviewMode: repo.reviewMode,
-            settings: (repo.settings ?? DEFAULT_REPO_SETTINGS),
+            settings: resolveEffectiveRepoSettings(repo.settings),
             source: 'repo',
         };
     }
@@ -122,7 +129,7 @@ export async function getEffectiveRepoSettings(db, repo) {
             providerChain: (globalSettings.providerChain ?? []),
             aiReviewEnabled: globalSettings.aiReviewEnabled,
             reviewMode: globalSettings.reviewMode,
-            settings: (globalSettings.settings ?? DEFAULT_REPO_SETTINGS),
+            settings: resolveEffectiveRepoSettings(globalSettings.settings),
             source: 'global',
         };
     }
@@ -131,7 +138,7 @@ export async function getEffectiveRepoSettings(db, repo) {
         providerChain: [],
         aiReviewEnabled: true,
         reviewMode: 'simple',
-        settings: DEFAULT_REPO_SETTINGS,
+        settings: resolveEffectiveRepoSettings(DEFAULT_REPO_SETTINGS),
         source: 'global',
     };
 }
@@ -222,6 +229,212 @@ export async function saveReview(db, data) {
     // biome-ignore lint/style/noNonNullAssertion: drizzle .returning() always returns for insert/update
     return result;
 }
+// ─── Issue Drafts (Issue-Triage Agent) ──────────────────────────
+/**
+ * Persist a triage DRAFT produced by the issue-analysis worker.
+ *
+ * The worker NEVER posts a GitHub comment — it only inserts a DRAFT row that a
+ * human later approves in the dashboard. The `issue_drafts` table enforces a
+ * partial-unique invariant: AT MOST ONE open DRAFT per (repository, issue)
+ * (uq_issue_drafts_open_draft, predicate `status = 'DRAFT'`).
+ *
+ * Conflict handling (DECISION): we `onConflictDoNothing` on that partial-unique
+ * index. If a DRAFT for this (repo, issue) is already open, the insert is a
+ * no-op and this returns `undefined` — the caller treats that as "a draft
+ * already exists, skip" rather than overwriting an in-flight human review or
+ * throwing. Re-triaging is allowed only after the prior draft is decided
+ * (APPROVED/REJECTED/POSTED rows fall outside the partial predicate).
+ *
+ * @returns the inserted row, or `undefined` when an open DRAFT already existed.
+ */
+export async function saveIssueDraft(db, data) {
+    const [result] = await db
+        .insert(issueDrafts)
+        .values(data)
+        // Target the partial-unique "one open DRAFT per (repo, issue)" index. The
+        // WHERE mirrors the index predicate so Postgres matches the SAME partial
+        // index. On conflict: do nothing (skip) — returning() yields no row.
+        .onConflictDoNothing({
+        target: [issueDrafts.repositoryId, issueDrafts.issueNumber],
+        where: sql `${issueDrafts.status} = 'DRAFT'`,
+    })
+        .returning();
+    return result;
+}
+/**
+ * Fetch the currently-open DRAFT (if any) for a given (repository, issue).
+ *
+ * Mirrors the partial-unique invariant enforced by `uq_issue_drafts_open_draft`
+ * (predicate `status = 'DRAFT'`): at most one open DRAFT exists per (repo,
+ * issue), so this returns either that single row or `undefined`.
+ *
+ * The issue-analysis worker calls this BEFORE the expensive dedup/LLM stages so
+ * a retry (or a re-triage while a human is still reviewing the prior draft) can
+ * skip early instead of re-charging the LLM and then silently discarding the
+ * result at the onConflictDoNothing insert.
+ *
+ * @returns the open DRAFT row, or `undefined` when none is open.
+ */
+export async function getOpenIssueDraft(db, repositoryId, issueNumber) {
+    const [row] = await db
+        .select()
+        .from(issueDrafts)
+        .where(and(eq(issueDrafts.repositoryId, repositoryId), eq(issueDrafts.issueNumber, issueNumber), eq(issueDrafts.status, 'DRAFT')))
+        .limit(1);
+    return row;
+}
+/**
+ * List issue drafts visible to a set of repositories, newest-first.
+ *
+ * SCOPING: the caller MUST pass `repositoryIds` already restricted to the
+ * authenticated user's repos (see the approval API — it resolves these from
+ * `user.installationIds`). This query NEVER widens scope on its own: an empty
+ * `repositoryIds` returns an empty list (no rows), so a user with no repos can
+ * never see another tenant's drafts. `status` is an optional additional filter.
+ */
+export async function listIssueDrafts(db, repositoryIds, options) {
+    if (repositoryIds.length === 0)
+        return [];
+    const limit = Math.min(options?.limit ?? 50, 100);
+    const offset = options?.offset ?? 0;
+    const conditions = [inArray(issueDrafts.repositoryId, repositoryIds)];
+    if (options?.status) {
+        conditions.push(eq(issueDrafts.status, options.status));
+    }
+    return db
+        .select()
+        .from(issueDrafts)
+        .where(and(...conditions))
+        .orderBy(desc(issueDrafts.createdAt))
+        .limit(limit)
+        .offset(offset);
+}
+/**
+ * Fetch a single issue draft by its primary key. No scoping is applied here —
+ * the caller MUST verify the row's `repositoryId` belongs to the authenticated
+ * user BEFORE returning it or acting on it (the approval API does this).
+ */
+export async function getIssueDraftById(db, id) {
+    const [row] = await db.select().from(issueDrafts).where(eq(issueDrafts.id, id)).limit(1);
+    return row;
+}
+/**
+ * Edit a draft's body (the human sanitizes/edits before posting). Only a row
+ * still in DRAFT status is editable — editing an APPROVED/POSTED/REJECTED row is
+ * a no-op (returns `undefined`), so a decided draft cannot be silently mutated.
+ */
+export async function updateIssueDraftBody(db, id, body) {
+    const [row] = await db
+        .update(issueDrafts)
+        .set({ body, updatedAt: new Date() })
+        .where(and(eq(issueDrafts.id, id), eq(issueDrafts.status, 'DRAFT')))
+        .returning();
+    return row;
+}
+/**
+ * Atomically CLAIM a DRAFT for posting by flipping it to APPROVED.
+ *
+ * This is the POSTING LOCK that makes the GitHub post exactly-once. The WHERE
+ * clause pins `status = 'DRAFT'` and the UPDATE ... RETURNING is a single atomic
+ * compare-and-swap (CAS): of N concurrent approvers, EXACTLY ONE matches the row
+ * (DRAFT → APPROVED) and gets it back; every other caller matches ZERO rows and
+ * gets `undefined`. The winner — and only the winner — proceeds to postComment.
+ *
+ * APPROVED is therefore a TRANSIENT "posting in progress" state, NOT a terminal
+ * decision: it resolves forward to POSTED (markIssueDraftPosted) on a successful
+ * post, or back to DRAFT (releaseIssueDraftClaim) when the post fails so a human
+ * can retry. The caller MUST treat `undefined` as "another approver already
+ * claimed this — return 409 and do NOT post".
+ *
+ * Lifecycle: DRAFT → APPROVED (posting) → POSTED  (or → DRAFT on post failure).
+ */
+export async function claimIssueDraftForPosting(db, id) {
+    const [row] = await db
+        .update(issueDrafts)
+        // claimedAt stamps the posting lease (see findStaleApprovedDrafts): a reaper
+        // uses it to detect an APPROVED draft whose poster crashed before posting.
+        .set({ status: 'APPROVED', claimedAt: new Date(), updatedAt: new Date() })
+        .where(and(eq(issueDrafts.id, id), eq(issueDrafts.status, 'DRAFT')))
+        .returning();
+    return row;
+}
+/**
+ * RELEASE a posting claim by reverting APPROVED → DRAFT after a FAILED post.
+ *
+ * The CAS pins `status = 'APPROVED'` so this only ever un-does an in-flight
+ * posting claim (never a POSTED/REJECTED terminal row). After release the draft
+ * is editable/approvable again, so the human can retry. Returns the reverted row,
+ * or `undefined` when the row was no longer APPROVED (defensive — should not
+ * happen on the post-failure path since the claimer owns the APPROVED row).
+ */
+export async function releaseIssueDraftClaim(db, id) {
+    const [row] = await db
+        .update(issueDrafts)
+        // Clear the posting lease so a subsequent re-claim gets a fresh claimedAt
+        // (a stale lease would otherwise make the re-claimed draft look orphaned).
+        .set({ status: 'DRAFT', claimedAt: null, updatedAt: new Date() })
+        .where(and(eq(issueDrafts.id, id), eq(issueDrafts.status, 'APPROVED')))
+        .returning();
+    return row;
+}
+/**
+ * Atomically transition an APPROVED (claimed-for-posting) draft to POSTED,
+ * recording the GitHub comment id.
+ *
+ * IDEMPOTENCY/LIFECYCLE: the WHERE clause pins `status = 'APPROVED'` — only the
+ * approver that WON the posting claim (claimIssueDraftForPosting) and actually
+ * posted the comment reaches this. A row that is not APPROVED matches ZERO rows
+ * and returns `undefined`. Combined with the claim CAS this guarantees the post
+ * is recorded exactly once. The caller MUST treat `undefined` as "already
+ * decided, do not pretend we re-posted".
+ */
+export async function markIssueDraftPosted(db, id, postedCommentId) {
+    const [row] = await db
+        .update(issueDrafts)
+        .set({ status: 'POSTED', postedCommentId, updatedAt: new Date() })
+        .where(and(eq(issueDrafts.id, id), eq(issueDrafts.status, 'APPROVED')))
+        .returning();
+    return row;
+}
+/**
+ * Transition a DRAFT to REJECTED — no comment is ever posted. Same DRAFT-only
+ * guard as the post transition: a decided row is not re-rejected (returns
+ * `undefined`).
+ */
+export async function rejectIssueDraft(db, id) {
+    const [row] = await db
+        .update(issueDrafts)
+        .set({ status: 'REJECTED', updatedAt: new Date() })
+        .where(and(eq(issueDrafts.id, id), eq(issueDrafts.status, 'DRAFT')))
+        .returning();
+    return row;
+}
+/**
+ * DETECT stuck/orphaned APPROVED drafts whose posting lease is older than
+ * `olderThan` — the reaper-detection primitive (RES-001).
+ *
+ * APPROVED is a TRANSIENT "posting in progress" state (see
+ * claimIssueDraftForPosting). If the poster process crashes AFTER claiming
+ * (DRAFT → APPROVED, stamping `claimedAt`) but BEFORE it reaches POSTED or
+ * releases back to DRAFT, the row is stuck in APPROVED forever with no signal.
+ * This query surfaces those rows: status = APPROVED AND claimedAt IS NOT NULL
+ * AND claimedAt < olderThan, oldest-lease-first, capped at 100.
+ *
+ * It ONLY DETECTS — it takes no recovery action. The caller (PR2's reaper
+ * worker) decides what to do with each returned row: release it back to DRAFT
+ * via `releaseIssueDraftClaim` so a human can retry, or alert an operator.
+ *
+ * Global (not tenant-scoped): the reaper is a system maintenance job over the
+ * whole table, not a user-facing listing.
+ */
+export async function findStaleApprovedDrafts(db, olderThan) {
+    return db
+        .select()
+        .from(issueDrafts)
+        .where(and(eq(issueDrafts.status, 'APPROVED'), isNotNull(issueDrafts.claimedAt), lt(issueDrafts.claimedAt, olderThan)))
+        .orderBy(asc(issueDrafts.claimedAt))
+        .limit(100);
+}
 export async function getReviewsByRepoId(db, repositoryId, options = {}) {
     const { limit = 50, offset = 0 } = options;
     return db
@@ -1081,4 +1294,886 @@ export async function clearEmptyMemorySessions(db, installationId, project) {
         .returning({ id: memorySessions.id });
     return { deletedCount: result.length };
 }
+const explanationIdentityTextFields = [
+    'forgeInstance',
+    'installationId',
+    'actorId',
+    'repositoryId',
+    'requestedHeadSha',
+    'sourceCommentId',
+];
+/**
+ * Validates only the immutable identity shape. Opaque forge values are preserved
+ * byte-for-byte; especially, questionHash is never trimmed or case-folded.
+ */
+export function isValidExplanationInvocationIdentity(identity) {
+    if (typeof identity !== 'object' || identity === null)
+        return false;
+    const candidate = identity;
+    const pullRequestNumber = candidate.pullRequestNumber;
+    if (typeof pullRequestNumber !== 'number' ||
+        !Number.isSafeInteger(pullRequestNumber) ||
+        pullRequestNumber <= 0)
+        return false;
+    if (typeof candidate.questionHash !== 'string' || !/^[a-f0-9]{64}$/.test(candidate.questionHash))
+        return false;
+    return explanationIdentityTextFields.every((field) => typeof candidate[field] === 'string' && candidate[field].length > 0);
+}
+export function isValidExplanationInvocationRequest(request) {
+    if (!isValidExplanationInvocationIdentity(request))
+        return false;
+    const candidate = request;
+    return (typeof candidate.question === 'string' &&
+        candidate.question.length > 0 &&
+        createHash('sha256').update(candidate.question).digest('hex') === candidate.questionHash);
+}
+/**
+ * Produces an unambiguous SHA-256 key from the complete immutable tuple.
+ * JSON array encoding prevents delimiter ambiguity between opaque identifiers.
+ */
+export function deriveExplanationInvocationKey(identity) {
+    if (!isValidExplanationInvocationIdentity(identity))
+        return null;
+    return createHash('sha256')
+        .update(JSON.stringify([
+        'explanation-invocation-v1',
+        identity.forgeInstance,
+        identity.installationId,
+        identity.actorId,
+        identity.repositoryId,
+        identity.pullRequestNumber,
+        identity.requestedHeadSha,
+        identity.sourceCommentId,
+        identity.questionHash,
+    ]))
+        .digest('hex');
+}
+function matchesExplanationIdentity(row, identity) {
+    return (row.forgeInstance === identity.forgeInstance &&
+        row.installationId === identity.installationId &&
+        row.actorId === identity.actorId &&
+        row.repositoryId === identity.repositoryId &&
+        row.pullRequestNumber === identity.pullRequestNumber &&
+        row.requestedHeadSha === identity.requestedHeadSha &&
+        row.sourceCommentId === identity.sourceCommentId &&
+        row.questionHash === identity.questionHash &&
+        row.question === identity.question);
+}
+async function selectExplanationInvocationByKey(db, invocationKey) {
+    const [row] = await db
+        .select()
+        .from(explanationInvocations)
+        .where(eq(explanationInvocations.invocationKey, invocationKey))
+        .limit(1);
+    return row;
+}
+/**
+ * Inserts the sole pending claim, then separately observes a conflict. The
+ * conflict follow-up is mandatory: a missing row is unavailable, never permission
+ * to dispatch. This function creates no reservation or lifecycle authority.
+ */
+export async function registerExplanationInvocation(db, request) {
+    if (!isValidExplanationInvocationRequest(request))
+        return { status: 'invalid' };
+    const invocationKey = deriveExplanationInvocationKey(request);
+    if (invocationKey === null)
+        return { status: 'invalid' };
+    const [inserted] = await db
+        .insert(explanationInvocations)
+        .values({
+        invocationKey,
+        forgeInstance: request.forgeInstance,
+        installationId: request.installationId,
+        actorId: request.actorId,
+        repositoryId: request.repositoryId,
+        pullRequestNumber: request.pullRequestNumber,
+        requestedHeadSha: request.requestedHeadSha,
+        sourceCommentId: request.sourceCommentId,
+        questionHash: request.questionHash,
+        question: request.question,
+    })
+        .onConflictDoNothing({ target: explanationInvocations.invocationKey })
+        .returning();
+    if (inserted)
+        return { status: 'registered', invocation: inserted };
+    const observed = await selectExplanationInvocationByKey(db, invocationKey);
+    if (!observed)
+        return { status: 'unavailable' };
+    if (!matchesExplanationIdentity(observed, request))
+        return { status: 'mismatch' };
+    return { status: 'duplicate', invocation: observed };
+}
+/**
+ * Fetches an invocation only when the caller supplies its complete expected
+ * identity. A derived-key collision or changed tuple is deliberately opaque.
+ */
+export async function lookupExplanationInvocation(db, request) {
+    if (!isValidExplanationInvocationRequest(request))
+        return { status: 'invalid' };
+    const invocationKey = deriveExplanationInvocationKey(request);
+    if (invocationKey === null)
+        return { status: 'invalid' };
+    const observed = await selectExplanationInvocationByKey(db, invocationKey);
+    if (!observed)
+        return { status: 'not_found' };
+    if (!matchesExplanationIdentity(observed, request))
+        return { status: 'mismatch' };
+    return { status: 'found', invocation: observed };
+}
+const MIN_EXPLANATION_DISPATCH_LEASE_MS = 1_000;
+const MAX_EXPLANATION_DISPATCH_LEASE_MS = 300_000;
+function isValidExplanationInvocationDispatchReservationRequest(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const request = value;
+    return (hasOnlyFields(request, [
+        'forgeInstance',
+        'installationId',
+        'actorId',
+        'repositoryId',
+        'pullRequestNumber',
+        'requestedHeadSha',
+        'sourceCommentId',
+        'questionHash',
+        'question',
+        'leaseDurationMs',
+    ]) &&
+        isValidExplanationInvocationRequest(request) &&
+        typeof request.leaseDurationMs === 'number' &&
+        Number.isSafeInteger(request.leaseDurationMs) &&
+        request.leaseDurationMs >= MIN_EXPLANATION_DISPATCH_LEASE_MS &&
+        request.leaseDurationMs <= MAX_EXPLANATION_DISPATCH_LEASE_MS);
+}
+/** A returned reservation authorizes only post-commit external I/O; this function never commits a caller transaction. */
+export async function reserveExplanationInvocationDispatch(db, value) {
+    if (!isValidExplanationInvocationDispatchReservationRequest(value))
+        return { status: 'invalid' };
+    const invocationKey = deriveExplanationInvocationKey(value);
+    if (invocationKey === null)
+        return { status: 'invalid' };
+    const [reserved] = await db
+        .update(explanationInvocations)
+        .set({
+        executionStatus: 'DISPATCH_RESERVED',
+        executionFence: sql `gen_random_uuid()::text`,
+        dispatchReservedAt: sql `clock_timestamp()`,
+        dispatchLeaseExpiresAt: sql `clock_timestamp() + (${value.leaseDurationMs} * interval '1 millisecond')`,
+    })
+        .where(and(eq(explanationInvocations.invocationKey, invocationKey), eq(explanationInvocations.forgeInstance, value.forgeInstance), eq(explanationInvocations.installationId, value.installationId), eq(explanationInvocations.actorId, value.actorId), eq(explanationInvocations.repositoryId, value.repositoryId), eq(explanationInvocations.pullRequestNumber, value.pullRequestNumber), eq(explanationInvocations.requestedHeadSha, value.requestedHeadSha), eq(explanationInvocations.sourceCommentId, value.sourceCommentId), eq(explanationInvocations.questionHash, value.questionHash), eq(explanationInvocations.question, value.question), eq(explanationInvocations.executionStatus, 'PENDING'), isNull(explanationInvocations.executionFence), isNull(explanationInvocations.dispatchReservedAt), isNull(explanationInvocations.dispatchLeaseExpiresAt), isNull(explanationInvocations.outcomeStatus), isNull(explanationInvocations.outcomeAnswer), isNull(explanationInvocations.outcomePayload), isNull(explanationInvocations.outcomeCompletedAt)))
+        .returning();
+    if (reserved && isNonEmptyText(reserved.executionFence)) {
+        return { status: 'reserved', invocation: reserved, executionFence: reserved.executionFence };
+    }
+    const [observed] = await db
+        .select()
+        .from(explanationInvocations)
+        .where(and(eq(explanationInvocations.invocationKey, invocationKey), eq(explanationInvocations.question, value.question)))
+        .limit(1);
+    return observed && matchesExplanationIdentity(observed, value)
+        ? { status: 'observed', invocation: observed }
+        : { status: 'unavailable' };
+}
+function isValidExplanationInvocationExpiredDispatchRecoveryRequest(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const request = value;
+    return (hasOnlyFields(request, [
+        'forgeInstance',
+        'installationId',
+        'actorId',
+        'repositoryId',
+        'pullRequestNumber',
+        'requestedHeadSha',
+        'sourceCommentId',
+        'questionHash',
+        'question',
+        'executionFence',
+    ]) &&
+        isValidExplanationInvocationRequest(request) &&
+        isNonEmptyText(request.executionFence));
+}
+export async function recoverExpiredExplanationInvocationDispatch(db, value) {
+    if (!isValidExplanationInvocationExpiredDispatchRecoveryRequest(value))
+        return { status: 'invalid' };
+    const invocationKey = deriveExplanationInvocationKey(value);
+    if (invocationKey === null)
+        return { status: 'invalid' };
+    const conditions = [
+        eq(explanationInvocations.invocationKey, invocationKey),
+        eq(explanationInvocations.forgeInstance, value.forgeInstance),
+        eq(explanationInvocations.installationId, value.installationId),
+        eq(explanationInvocations.actorId, value.actorId),
+        eq(explanationInvocations.repositoryId, value.repositoryId),
+        eq(explanationInvocations.pullRequestNumber, value.pullRequestNumber),
+        eq(explanationInvocations.requestedHeadSha, value.requestedHeadSha),
+        eq(explanationInvocations.sourceCommentId, value.sourceCommentId),
+        eq(explanationInvocations.questionHash, value.questionHash),
+        eq(explanationInvocations.question, value.question),
+        eq(explanationInvocations.executionStatus, 'DISPATCH_RESERVED'),
+        eq(explanationInvocations.executionFence, value.executionFence),
+        isNull(explanationInvocations.outcomeStatus),
+        isNull(explanationInvocations.outcomeAnswer),
+        isNull(explanationInvocations.outcomePayload),
+        isNull(explanationInvocations.outcomeCompletedAt),
+    ];
+    const locked = db.$with('locked_expired_explanation_invocation').as(db
+        .select({
+        id: explanationInvocations.id,
+        lease: explanationInvocations.dispatchLeaseExpiresAt,
+    })
+        .from(explanationInvocations)
+        .where(and(...conditions))
+        .for('update'));
+    const outcome = {
+        kind: 'AMBIGUOUS',
+        reason: 'dispatch lease expired before durable completion',
+    };
+    const [recovered] = await db
+        .with(locked)
+        .update(explanationInvocations)
+        .set({
+        executionStatus: 'AMBIGUOUS',
+        outcomeStatus: 'AMBIGUOUS',
+        outcomeAnswer: null,
+        outcomePayload: outcome,
+        outcomeCompletedAt: sql `clock_timestamp()`,
+    })
+        .from(locked)
+        .where(and(eq(explanationInvocations.id, locked.id), lt(locked.lease, sql `clock_timestamp()`)))
+        .returning();
+    return recovered ? { status: 'recovered', invocation: recovered } : { status: 'unavailable' };
+}
+// ─── Explanation Invocation Settlement ──────────────────────────
+export const EXPLANATION_TERMINAL_OUTCOME_KINDS = [
+    'ANSWERED',
+    'INVALID',
+    'UNAUTHORIZED',
+    'DISABLED',
+    'STALE',
+    'AI_UNAVAILABLE',
+    'AMBIGUOUS',
+];
+const pendingTerminalOutcomeKinds = [
+    'INVALID',
+    'UNAUTHORIZED',
+    'DISABLED',
+    'STALE',
+    'AI_UNAVAILABLE',
+];
+function isNonEmptyText(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+function hasOnlyFields(value, fields) {
+    return Object.keys(value).every((field) => fields.includes(field));
+}
+function isValidExplanationOutcomePayload(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const payload = value;
+    if (!EXPLANATION_TERMINAL_OUTCOME_KINDS.includes(payload.kind)) {
+        return false;
+    }
+    if (payload.kind === 'ANSWERED') {
+        if (!hasOnlyFields(payload, ['kind', 'answer', 'metadata']) ||
+            !isNonEmptyText(payload.answer)) {
+            return false;
+        }
+        if (typeof payload.metadata !== 'object' ||
+            payload.metadata === null ||
+            Array.isArray(payload.metadata)) {
+            return false;
+        }
+        const metadata = payload.metadata;
+        return (hasOnlyFields(metadata, ['provider', 'model', 'tokensUsed']) &&
+            isNonEmptyText(metadata.provider) &&
+            isNonEmptyText(metadata.model) &&
+            typeof metadata.tokensUsed === 'number' &&
+            Number.isFinite(metadata.tokensUsed) &&
+            Number.isSafeInteger(metadata.tokensUsed) &&
+            metadata.tokensUsed >= 0);
+    }
+    return hasOnlyFields(payload, ['kind', 'reason']) && isNonEmptyText(payload.reason);
+}
+/** Validates the complete immutable settlement request before any database access. */
+export function validateExplanationInvocationSettlement(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return null;
+    const request = value;
+    if (!hasOnlyFields(request, [
+        'forgeInstance',
+        'installationId',
+        'actorId',
+        'repositoryId',
+        'pullRequestNumber',
+        'requestedHeadSha',
+        'sourceCommentId',
+        'questionHash',
+        'question',
+        'expectedExecutionStatus',
+        'executionFence',
+        'outcome',
+    ]) ||
+        !isValidExplanationInvocationRequest(request) ||
+        !isValidExplanationOutcomePayload(request.outcome) ||
+        (request.expectedExecutionStatus !== 'PENDING' &&
+            request.expectedExecutionStatus !== 'DISPATCH_RESERVED')) {
+        return null;
+    }
+    const outcome = request.outcome;
+    if (request.expectedExecutionStatus === 'PENDING') {
+        if (request.executionFence !== undefined ||
+            !pendingTerminalOutcomeKinds.some((kind) => kind === outcome.kind)) {
+            return null;
+        }
+    }
+    else if (!isNonEmptyText(request.executionFence) ||
+        !['ANSWERED', 'AI_UNAVAILABLE', 'AMBIGUOUS'].includes(outcome.kind)) {
+        return null;
+    }
+    return value;
+}
+function outcomeAnswer(payload) {
+    return payload.kind === 'ANSWERED' ? payload.answer : null;
+}
+function isCompleteExplanationInvocationOutcome(row) {
+    if (row.outcomeStatus !== row.executionStatus ||
+        row.outcomeCompletedAt === null ||
+        !isValidExplanationOutcomePayload(row.outcomePayload) ||
+        row.outcomePayload.kind !== row.executionStatus) {
+        return false;
+    }
+    return row.outcomeAnswer === outcomeAnswer(row.outcomePayload);
+}
+/**
+ * Performs one fenced conditional update. A zero-row result is observation-only:
+ * it grants no execution authority and never repairs legacy rows.
+ */
+export async function settleExplanationInvocation(db, value) {
+    const request = validateExplanationInvocationSettlement(value);
+    if (!request)
+        return { status: 'invalid' };
+    const invocationKey = deriveExplanationInvocationKey(request);
+    if (invocationKey === null)
+        return { status: 'invalid' };
+    const conditions = [
+        eq(explanationInvocations.invocationKey, invocationKey),
+        eq(explanationInvocations.forgeInstance, request.forgeInstance),
+        eq(explanationInvocations.installationId, request.installationId),
+        eq(explanationInvocations.actorId, request.actorId),
+        eq(explanationInvocations.repositoryId, request.repositoryId),
+        eq(explanationInvocations.pullRequestNumber, request.pullRequestNumber),
+        eq(explanationInvocations.requestedHeadSha, request.requestedHeadSha),
+        eq(explanationInvocations.sourceCommentId, request.sourceCommentId),
+        eq(explanationInvocations.questionHash, request.questionHash),
+        eq(explanationInvocations.question, request.question),
+        eq(explanationInvocations.executionStatus, request.expectedExecutionStatus),
+        sql `${explanationInvocations.outcomeStatus} IS NULL`,
+        sql `${explanationInvocations.outcomeAnswer} IS NULL`,
+        sql `${explanationInvocations.outcomePayload} IS NULL`,
+        sql `${explanationInvocations.outcomeCompletedAt} IS NULL`,
+    ];
+    const postLockConditions = [];
+    const executionFence = request.executionFence;
+    if (request.expectedExecutionStatus === 'PENDING') {
+        conditions.push(isNull(explanationInvocations.executionFence), isNull(explanationInvocations.dispatchReservedAt), isNull(explanationInvocations.dispatchLeaseExpiresAt));
+    }
+    else {
+        if (executionFence === undefined)
+            return { status: 'invalid' };
+        conditions.push(eq(explanationInvocations.executionFence, executionFence));
+        if (request.outcome.kind !== 'AMBIGUOUS') {
+            postLockConditions.push(gt(explanationInvocations.dispatchLeaseExpiresAt, sql `clock_timestamp()`));
+        }
+    }
+    const locked = db
+        .select({
+        id: explanationInvocations.id,
+        dispatchLeaseExpiresAt: explanationInvocations.dispatchLeaseExpiresAt,
+    })
+        .from(explanationInvocations)
+        .where(and(...conditions))
+        .for('update')
+        .as('locked_explanation_invocation');
+    const [settled] = await db
+        .update(explanationInvocations)
+        .set({
+        executionStatus: request.outcome.kind,
+        outcomeStatus: request.outcome.kind,
+        outcomeAnswer: outcomeAnswer(request.outcome),
+        outcomePayload: request.outcome,
+        outcomeCompletedAt: sql `now()`,
+    })
+        .from(locked)
+        .where(and(eq(explanationInvocations.id, locked.id), ...postLockConditions))
+        .returning();
+    if (settled)
+        return { status: 'settled', invocation: settled };
+    const [observed] = await db
+        .select()
+        .from(explanationInvocations)
+        .where(and(eq(explanationInvocations.invocationKey, invocationKey), eq(explanationInvocations.forgeInstance, request.forgeInstance), eq(explanationInvocations.installationId, request.installationId), eq(explanationInvocations.actorId, request.actorId), eq(explanationInvocations.repositoryId, request.repositoryId), eq(explanationInvocations.pullRequestNumber, request.pullRequestNumber), eq(explanationInvocations.requestedHeadSha, request.requestedHeadSha), eq(explanationInvocations.sourceCommentId, request.sourceCommentId), eq(explanationInvocations.questionHash, request.questionHash), eq(explanationInvocations.question, request.question), inArray(explanationInvocations.executionStatus, EXPLANATION_TERMINAL_OUTCOME_KINDS), isNotNull(explanationInvocations.outcomeStatus), isNotNull(explanationInvocations.outcomePayload), isNotNull(explanationInvocations.outcomeCompletedAt)))
+        .limit(1);
+    return observed && isCompleteExplanationInvocationOutcome(observed)
+        ? { status: 'settled', invocation: observed }
+        : { status: 'unavailable' };
+}
+/**
+ * Bounded ingress recovery: convert a claim whose queue admission is unknown
+ * into an explicit terminal ambiguity. The identity and PENDING CAS make this
+ * safe to call repeatedly and prevent a later worker from dispatching it.
+ */
+export async function recoverPendingExplanationInvocation(db, value) {
+    if (!isValidExplanationInvocationRequest(value))
+        return { status: 'invalid' };
+    const invocationKey = deriveExplanationInvocationKey(value);
+    if (invocationKey === null)
+        return { status: 'invalid' };
+    const outcome = {
+        kind: 'AMBIGUOUS',
+        reason: 'Explanation queue admission could not be confirmed.',
+    };
+    const [settled] = await db
+        .update(explanationInvocations)
+        .set({
+        executionStatus: 'AMBIGUOUS',
+        outcomeStatus: 'AMBIGUOUS',
+        outcomeAnswer: null,
+        outcomePayload: outcome,
+        outcomeCompletedAt: sql `now()`,
+    })
+        .where(and(...explanationPublicationIdentityConditions(invocationKey, value), eq(explanationInvocations.executionStatus, 'PENDING'), isNull(explanationInvocations.executionFence), isNull(explanationInvocations.outcomeStatus), isNull(explanationInvocations.outcomePayload), isNull(explanationInvocations.outcomeCompletedAt)))
+        .returning();
+    return settled ? { status: 'settled', invocation: settled } : { status: 'unavailable' };
+}
+// ─── Explanation Publication CREATE ─────────────────────────────
+export const EXPLANATION_PUBLICATION_CHANNELS = {
+    PROGRESS: 'progress',
+    ANSWER: 'answer',
+};
+export const EXPLANATION_PUBLICATION_CREATE_OUTCOMES = {
+    ACKNOWLEDGED: 'ACKNOWLEDGED',
+    UNCERTAIN: 'UNCERTAIN',
+};
+const MAX_POSTGRES_INT32 = 2_147_483_647;
+/**
+ * Reservation advances the stored version once and must leave room for the
+ * subsequent fenced settlement to advance it again.
+ */
+function isValidPublicationReservationVersion(value) {
+    return (typeof value === 'number' &&
+        Number.isSafeInteger(value) &&
+        value >= 0 &&
+        value < MAX_POSTGRES_INT32 - 1);
+}
+/** Settlement receives the reservation's current persisted version and advances it once. */
+function isValidPublicationSettlementVersion(value) {
+    return (typeof value === 'number' &&
+        Number.isSafeInteger(value) &&
+        value > 0 &&
+        value < MAX_POSTGRES_INT32);
+}
+function isValidPositiveSafeId(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value > 0;
+}
+function isExplanationPublicationChannel(value) {
+    return (value === EXPLANATION_PUBLICATION_CHANNELS.PROGRESS ||
+        value === EXPLANATION_PUBLICATION_CHANNELS.ANSWER);
+}
+function isValidExplanationPublicationStaleRequest(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const request = value;
+    return (hasOnlyFields(request, [
+        'forgeInstance',
+        'installationId',
+        'actorId',
+        'repositoryId',
+        'pullRequestNumber',
+        'requestedHeadSha',
+        'sourceCommentId',
+        'questionHash',
+        'question',
+        'channel',
+    ]) &&
+        isValidExplanationInvocationRequest(request) &&
+        isExplanationPublicationChannel(request.channel));
+}
+function hasCompleteExplanationPublicationIdentity(request, isValidVersion) {
+    return (hasOnlyFields(request, [
+        'forgeInstance',
+        'installationId',
+        'actorId',
+        'repositoryId',
+        'pullRequestNumber',
+        'requestedHeadSha',
+        'sourceCommentId',
+        'questionHash',
+        'question',
+        'channel',
+        'expectedPublicationVersion',
+        'expectedBotAuthorId',
+    ]) &&
+        isValidExplanationInvocationRequest(request) &&
+        isExplanationPublicationChannel(request.channel) &&
+        isValidVersion(request.expectedPublicationVersion) &&
+        isValidPositiveSafeId(request.expectedBotAuthorId));
+}
+/** Validates the complete immutable identity and CREATE fence before database access. */
+export function validateExplanationPublicationCreateReservation(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return null;
+    return hasCompleteExplanationPublicationIdentity(value, isValidPublicationReservationVersion)
+        ? value
+        : null;
+}
+/** Validates fenced CREATE settlement input without accepting caller-controlled lifecycle fields. */
+export function validateExplanationPublicationCreateSettlement(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return null;
+    const request = value;
+    if (!hasOnlyFields(request, [
+        'forgeInstance',
+        'installationId',
+        'actorId',
+        'repositoryId',
+        'pullRequestNumber',
+        'requestedHeadSha',
+        'sourceCommentId',
+        'questionHash',
+        'question',
+        'channel',
+        'expectedPublicationVersion',
+        'expectedBotAuthorId',
+        'publicationFence',
+        'outcome',
+        'commentId',
+    ]) ||
+        !isNonEmptyText(request.publicationFence) ||
+        (request.outcome !== EXPLANATION_PUBLICATION_CREATE_OUTCOMES.ACKNOWLEDGED &&
+            request.outcome !== EXPLANATION_PUBLICATION_CREATE_OUTCOMES.UNCERTAIN)) {
+        return null;
+    }
+    const reservation = {
+        forgeInstance: request.forgeInstance,
+        installationId: request.installationId,
+        actorId: request.actorId,
+        repositoryId: request.repositoryId,
+        pullRequestNumber: request.pullRequestNumber,
+        requestedHeadSha: request.requestedHeadSha,
+        sourceCommentId: request.sourceCommentId,
+        questionHash: request.questionHash,
+        question: request.question,
+        channel: request.channel,
+        expectedPublicationVersion: request.expectedPublicationVersion,
+        expectedBotAuthorId: request.expectedBotAuthorId,
+    };
+    if (!hasCompleteExplanationPublicationIdentity(reservation, isValidPublicationSettlementVersion))
+        return null;
+    if (request.outcome === EXPLANATION_PUBLICATION_CREATE_OUTCOMES.ACKNOWLEDGED) {
+        return isValidPositiveSafeId(request.commentId)
+            ? value
+            : null;
+    }
+    return request.commentId === undefined
+        ? value
+        : null;
+}
+function explanationPublicationIdentityConditions(invocationKey, request) {
+    return [
+        eq(explanationInvocations.invocationKey, invocationKey),
+        eq(explanationInvocations.forgeInstance, request.forgeInstance),
+        eq(explanationInvocations.installationId, request.installationId),
+        eq(explanationInvocations.actorId, request.actorId),
+        eq(explanationInvocations.repositoryId, request.repositoryId),
+        eq(explanationInvocations.pullRequestNumber, request.pullRequestNumber),
+        eq(explanationInvocations.requestedHeadSha, request.requestedHeadSha),
+        eq(explanationInvocations.sourceCommentId, request.sourceCommentId),
+        eq(explanationInvocations.questionHash, request.questionHash),
+        eq(explanationInvocations.question, request.question),
+    ];
+}
+async function observeExplanationPublication(db, invocationKey, request) {
+    const [observed] = await db
+        .select()
+        .from(explanationInvocations)
+        .where(and(...explanationPublicationIdentityConditions(invocationKey, request)))
+        .limit(1);
+    return observed;
+}
+/**
+ * Records a superseded target without mutating its generation outcome, visible
+ * comment identity, publication version, or the other publication channel.
+ */
+export async function markExplanationPublicationStale(db, value) {
+    if (!isValidExplanationPublicationStaleRequest(value)) {
+        return { status: 'invalid' };
+    }
+    const staleRequest = value;
+    const invocationKey = deriveExplanationInvocationKey(staleRequest);
+    if (invocationKey === null)
+        return { status: 'invalid' };
+    const conditions = explanationPublicationIdentityConditions(invocationKey, staleRequest);
+    const [transitioned] = staleRequest.channel === EXPLANATION_PUBLICATION_CHANNELS.PROGRESS
+        ? await db
+            .update(explanationInvocations)
+            .set({ progressPublicationStatus: 'STALE' })
+            .where(and(...conditions, inArray(explanationInvocations.progressPublicationStatus, [
+            'NOT_STARTED',
+            'PUBLISHED',
+        ])))
+            .returning()
+        : await db
+            .update(explanationInvocations)
+            .set({ answerPublicationStatus: 'STALE' })
+            .where(and(...conditions, inArray(explanationInvocations.answerPublicationStatus, ['NOT_STARTED', 'PUBLISHED'])))
+            .returning();
+    if (transitioned)
+        return { status: 'stale', invocation: transitioned };
+    const observed = await observeExplanationPublication(db, invocationKey, staleRequest);
+    const status = staleRequest.channel === EXPLANATION_PUBLICATION_CHANNELS.PROGRESS
+        ? observed?.progressPublicationStatus
+        : observed?.answerPublicationStatus;
+    return observed && status === 'STALE'
+        ? { status: 'stale', invocation: observed }
+        : { status: 'unavailable' };
+}
+/**
+ * Persists the CREATE fence in one CAS before any caller can issue a comment POST.
+ * The supplied version is pre-reservation; the returned row carries the current
+ * reserved version that settlement must present exactly.
+ */
+export async function reserveExplanationPublicationCreate(db, value) {
+    const request = validateExplanationPublicationCreateReservation(value);
+    if (!request)
+        return { status: 'invalid' };
+    const invocationKey = deriveExplanationInvocationKey(request);
+    if (invocationKey === null)
+        return { status: 'invalid' };
+    const conditions = explanationPublicationIdentityConditions(invocationKey, request);
+    const [reserved] = request.channel === EXPLANATION_PUBLICATION_CHANNELS.PROGRESS
+        ? await db
+            .update(explanationInvocations)
+            .set({
+            progressPublicationStatus: 'CREATE_STARTED',
+            progressPublicationCreateStartedAt: sql `clock_timestamp()`,
+            progressExpectedBotAuthorId: request.expectedBotAuthorId,
+            progressPublicationFence: sql `gen_random_uuid()::text`,
+            progressPublicationVersion: request.expectedPublicationVersion + 1,
+        })
+            .where(and(...conditions, eq(explanationInvocations.progressPublicationStatus, 'NOT_STARTED'), eq(explanationInvocations.progressPublicationVersion, request.expectedPublicationVersion), isNull(explanationInvocations.progressPublicationCreateStartedAt), isNull(explanationInvocations.progressCommentId), isNull(explanationInvocations.progressExpectedBotAuthorId), isNull(explanationInvocations.progressPublicationFence)))
+            .returning()
+        : await db
+            .update(explanationInvocations)
+            .set({
+            answerPublicationStatus: 'CREATE_STARTED',
+            answerPublicationCreateStartedAt: sql `clock_timestamp()`,
+            answerExpectedBotAuthorId: request.expectedBotAuthorId,
+            answerPublicationFence: sql `gen_random_uuid()::text`,
+            answerPublicationVersion: request.expectedPublicationVersion + 1,
+        })
+            .where(and(...conditions, eq(explanationInvocations.answerPublicationStatus, 'NOT_STARTED'), eq(explanationInvocations.answerPublicationVersion, request.expectedPublicationVersion), isNull(explanationInvocations.answerPublicationCreateStartedAt), isNull(explanationInvocations.answerCommentId), isNull(explanationInvocations.answerExpectedBotAuthorId), isNull(explanationInvocations.answerPublicationFence)))
+            .returning();
+    const fence = request.channel === EXPLANATION_PUBLICATION_CHANNELS.PROGRESS
+        ? reserved?.progressPublicationFence
+        : reserved?.answerPublicationFence;
+    if (reserved && isNonEmptyText(fence)) {
+        return { status: 'reserved', invocation: reserved, publicationFence: fence };
+    }
+    const observed = await observeExplanationPublication(db, invocationKey, request);
+    return observed ? { status: 'observed', invocation: observed } : { status: 'unavailable' };
+}
+/**
+ * Consumes a persisted CREATE fence so a duplicate or late POST result cannot gain authority.
+ * The supplied version is the current reserved version; settlement increments it once.
+ */
+export async function settleExplanationPublicationCreate(db, value) {
+    const request = validateExplanationPublicationCreateSettlement(value);
+    if (!request)
+        return { status: 'invalid' };
+    const invocationKey = deriveExplanationInvocationKey(request);
+    if (invocationKey === null)
+        return { status: 'invalid' };
+    const conditions = explanationPublicationIdentityConditions(invocationKey, request);
+    const isAcknowledged = request.outcome === EXPLANATION_PUBLICATION_CREATE_OUTCOMES.ACKNOWLEDGED;
+    const [settled] = request.channel === EXPLANATION_PUBLICATION_CHANNELS.PROGRESS
+        ? await db
+            .update(explanationInvocations)
+            .set({
+            progressPublicationStatus: isAcknowledged ? 'PUBLISHED' : 'AMBIGUOUS',
+            progressCommentId: isAcknowledged ? request.commentId : null,
+            progressPublicationFence: null,
+            progressPublicationVersion: request.expectedPublicationVersion + 1,
+        })
+            .where(and(...conditions, eq(explanationInvocations.progressPublicationStatus, 'CREATE_STARTED'), eq(explanationInvocations.progressPublicationVersion, request.expectedPublicationVersion), eq(explanationInvocations.progressExpectedBotAuthorId, request.expectedBotAuthorId), eq(explanationInvocations.progressPublicationFence, request.publicationFence)))
+            .returning()
+        : await db
+            .update(explanationInvocations)
+            .set({
+            answerPublicationStatus: isAcknowledged ? 'PUBLISHED' : 'AMBIGUOUS',
+            answerCommentId: isAcknowledged ? request.commentId : null,
+            answerPublicationFence: null,
+            answerPublicationVersion: request.expectedPublicationVersion + 1,
+        })
+            .where(and(...conditions, eq(explanationInvocations.answerPublicationStatus, 'CREATE_STARTED'), eq(explanationInvocations.answerPublicationVersion, request.expectedPublicationVersion), eq(explanationInvocations.answerExpectedBotAuthorId, request.expectedBotAuthorId), eq(explanationInvocations.answerPublicationFence, request.publicationFence)))
+            .returning();
+    if (settled)
+        return { status: 'settled', invocation: settled };
+    const observed = await observeExplanationPublication(db, invocationKey, request);
+    return observed ? { status: 'observed', invocation: observed } : { status: 'unavailable' };
+}
+/** Validates a PATCH reservation against an existing immutable publication comment. */
+export function validateExplanationPublicationPatchReservation(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return null;
+    const request = value;
+    const reservation = {
+        forgeInstance: request.forgeInstance,
+        installationId: request.installationId,
+        actorId: request.actorId,
+        repositoryId: request.repositoryId,
+        pullRequestNumber: request.pullRequestNumber,
+        requestedHeadSha: request.requestedHeadSha,
+        sourceCommentId: request.sourceCommentId,
+        questionHash: request.questionHash,
+        question: request.question,
+        channel: request.channel,
+        expectedPublicationVersion: request.expectedPublicationVersion,
+        expectedBotAuthorId: request.expectedBotAuthorId,
+    };
+    return hasOnlyFields(request, [
+        'forgeInstance',
+        'installationId',
+        'actorId',
+        'repositoryId',
+        'pullRequestNumber',
+        'requestedHeadSha',
+        'sourceCommentId',
+        'questionHash',
+        'question',
+        'channel',
+        'expectedPublicationVersion',
+        'expectedBotAuthorId',
+        'commentId',
+    ]) &&
+        hasCompleteExplanationPublicationIdentity(reservation, isValidPublicationReservationVersion) &&
+        isValidPositiveSafeId(request.commentId)
+        ? value
+        : null;
+}
+/** Validates fenced PATCH settlement input without accepting caller lifecycle fields. */
+export function validateExplanationPublicationPatchSettlement(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return null;
+    const request = value;
+    if (!hasOnlyFields(request, [
+        'forgeInstance',
+        'installationId',
+        'actorId',
+        'repositoryId',
+        'pullRequestNumber',
+        'requestedHeadSha',
+        'sourceCommentId',
+        'questionHash',
+        'question',
+        'channel',
+        'expectedPublicationVersion',
+        'expectedBotAuthorId',
+        'commentId',
+        'publicationFence',
+        'outcome',
+    ]) ||
+        !isNonEmptyText(request.publicationFence) ||
+        (request.outcome !== EXPLANATION_PUBLICATION_CREATE_OUTCOMES.ACKNOWLEDGED &&
+            request.outcome !== EXPLANATION_PUBLICATION_CREATE_OUTCOMES.UNCERTAIN)) {
+        return null;
+    }
+    const reservation = {
+        forgeInstance: request.forgeInstance,
+        installationId: request.installationId,
+        actorId: request.actorId,
+        repositoryId: request.repositoryId,
+        pullRequestNumber: request.pullRequestNumber,
+        requestedHeadSha: request.requestedHeadSha,
+        sourceCommentId: request.sourceCommentId,
+        questionHash: request.questionHash,
+        question: request.question,
+        channel: request.channel,
+        expectedPublicationVersion: request.expectedPublicationVersion,
+        expectedBotAuthorId: request.expectedBotAuthorId,
+    };
+    return hasCompleteExplanationPublicationIdentity(reservation, isValidPublicationSettlementVersion) && isValidPositiveSafeId(request.commentId)
+        ? value
+        : null;
+}
+/** Persists PATCH_STARTED before caller I/O without changing the CREATE timestamp or comment. */
+export async function reserveExplanationPublicationPatch(db, value) {
+    const request = validateExplanationPublicationPatchReservation(value);
+    if (!request)
+        return { status: 'invalid' };
+    const invocationKey = deriveExplanationInvocationKey(request);
+    if (invocationKey === null)
+        return { status: 'invalid' };
+    const conditions = explanationPublicationIdentityConditions(invocationKey, request);
+    const [reserved] = request.channel === EXPLANATION_PUBLICATION_CHANNELS.PROGRESS
+        ? await db
+            .update(explanationInvocations)
+            .set({
+            progressPublicationStatus: 'PATCH_STARTED',
+            progressPublicationFence: sql `gen_random_uuid()::text`,
+            progressPublicationVersion: request.expectedPublicationVersion + 1,
+        })
+            .where(and(...conditions, eq(explanationInvocations.progressPublicationStatus, 'PUBLISHED'), eq(explanationInvocations.progressPublicationVersion, request.expectedPublicationVersion), eq(explanationInvocations.progressExpectedBotAuthorId, request.expectedBotAuthorId), eq(explanationInvocations.progressCommentId, request.commentId), isNull(explanationInvocations.progressPublicationFence)))
+            .returning()
+        : await db
+            .update(explanationInvocations)
+            .set({
+            answerPublicationStatus: 'PATCH_STARTED',
+            answerPublicationFence: sql `gen_random_uuid()::text`,
+            answerPublicationVersion: request.expectedPublicationVersion + 1,
+        })
+            .where(and(...conditions, eq(explanationInvocations.answerPublicationStatus, 'PUBLISHED'), eq(explanationInvocations.answerPublicationVersion, request.expectedPublicationVersion), eq(explanationInvocations.answerExpectedBotAuthorId, request.expectedBotAuthorId), eq(explanationInvocations.answerCommentId, request.commentId), isNull(explanationInvocations.answerPublicationFence)))
+            .returning();
+    const fence = request.channel === EXPLANATION_PUBLICATION_CHANNELS.PROGRESS
+        ? reserved?.progressPublicationFence
+        : reserved?.answerPublicationFence;
+    if (reserved && isNonEmptyText(fence)) {
+        return { status: 'reserved', invocation: reserved, publicationFence: fence };
+    }
+    const observed = await observeExplanationPublication(db, invocationKey, request);
+    return observed ? { status: 'observed', invocation: observed } : { status: 'unavailable' };
+}
+/** Consumes a matching PATCH fence and preserves the existing comment identity. */
+export async function settleExplanationPublicationPatch(db, value) {
+    const request = validateExplanationPublicationPatchSettlement(value);
+    if (!request)
+        return { status: 'invalid' };
+    const invocationKey = deriveExplanationInvocationKey(request);
+    if (invocationKey === null)
+        return { status: 'invalid' };
+    const conditions = explanationPublicationIdentityConditions(invocationKey, request);
+    const isAcknowledged = request.outcome === EXPLANATION_PUBLICATION_CREATE_OUTCOMES.ACKNOWLEDGED;
+    const [settled] = request.channel === EXPLANATION_PUBLICATION_CHANNELS.PROGRESS
+        ? await db
+            .update(explanationInvocations)
+            .set({
+            progressPublicationStatus: isAcknowledged ? 'PUBLISHED' : 'AMBIGUOUS',
+            progressPublicationFence: null,
+            progressPublicationVersion: request.expectedPublicationVersion + 1,
+        })
+            .where(and(...conditions, eq(explanationInvocations.progressPublicationStatus, 'PATCH_STARTED'), eq(explanationInvocations.progressPublicationVersion, request.expectedPublicationVersion), eq(explanationInvocations.progressExpectedBotAuthorId, request.expectedBotAuthorId), eq(explanationInvocations.progressCommentId, request.commentId), eq(explanationInvocations.progressPublicationFence, request.publicationFence)))
+            .returning()
+        : await db
+            .update(explanationInvocations)
+            .set({
+            answerPublicationStatus: isAcknowledged ? 'PUBLISHED' : 'AMBIGUOUS',
+            answerPublicationFence: null,
+            answerPublicationVersion: request.expectedPublicationVersion + 1,
+        })
+            .where(and(...conditions, eq(explanationInvocations.answerPublicationStatus, 'PATCH_STARTED'), eq(explanationInvocations.answerPublicationVersion, request.expectedPublicationVersion), eq(explanationInvocations.answerExpectedBotAuthorId, request.expectedBotAuthorId), eq(explanationInvocations.answerCommentId, request.commentId), eq(explanationInvocations.answerPublicationFence, request.publicationFence)))
+            .returning();
+    if (settled)
+        return { status: 'settled', invocation: settled };
+    const observed = await observeExplanationPublication(db, invocationKey, request);
+    return observed ? { status: 'observed', invocation: observed } : { status: 'unavailable' };
+}
 //# sourceMappingURL=queries.js.map