|
1 | 1 | import type { AppendEventInput, LedgerEntry } from "./event-ledger.js"; |
2 | | - |
3 | | -export const MINER_PR_OUTCOME_EVENT: "pr_outcome"; |
4 | | -export const MINER_PR_OUTCOME_DECISIONS: readonly ["merged", "closed"]; |
5 | | - |
6 | | -export type MinerPrOutcomeDecision = "merged" | "closed"; |
7 | | - |
8 | | -export interface NormalizedPrOutcomePayload { |
9 | | - prNumber: number; |
10 | | - decision: MinerPrOutcomeDecision; |
11 | | - closedAt: string | null; |
12 | | - reason: string | null; |
13 | | -} |
14 | | - |
15 | | -export interface PrOutcomeInput { |
16 | | - repoFullName?: unknown; |
17 | | - prNumber?: unknown; |
18 | | - decision?: unknown; |
19 | | - closedAt?: unknown; |
20 | | - reason?: unknown; |
21 | | -} |
22 | | - |
23 | | -export interface RecordPrOutcomeOptions { |
24 | | - /** Optional at the type level so a caller can pass an unusable ledger to exercise the fail-closed guard; the |
25 | | - * writer throws `invalid_event_ledger` at runtime when this is absent or lacks `appendEvent`. Reuses the |
26 | | - * real EventLedger#appendEvent signature so a genuine EventLedger (not just a same-shaped stub) type-checks. */ |
27 | | - eventLedger?: { appendEvent(event: AppendEventInput): LedgerEntry }; |
28 | | -} |
29 | | - |
30 | | -export interface PrOutcomeLedgerReader { |
31 | | - readEvents(filter?: { since?: number; repoFullName?: string }): unknown[]; |
32 | | -} |
33 | | - |
34 | | -export function normalizePrOutcomePayload(payload: unknown): NormalizedPrOutcomePayload | null; |
35 | | - |
36 | | -export function recordPrOutcomeSnapshot(input: PrOutcomeInput, options?: RecordPrOutcomeOptions): unknown; |
37 | | - |
38 | | -export function readPrOutcomes( |
39 | | - eventLedger: PrOutcomeLedgerReader, |
40 | | - filter?: { since?: number; repoFullName?: string }, |
41 | | -): Map<string, NormalizedPrOutcomePayload & { repoFullName: string }>; |
| 2 | +/** Event-ledger vocabulary for a miner-local PR outcome. */ |
| 3 | +export declare const MINER_PR_OUTCOME_EVENT: "pr_outcome"; |
| 4 | +/** The terminal decisions a miner records for one of its own PRs. */ |
| 5 | +export declare const MINER_PR_OUTCOME_DECISIONS: readonly ["merged", "closed"]; |
| 6 | +export type MinerPrOutcomeDecision = (typeof MINER_PR_OUTCOME_DECISIONS)[number]; |
| 7 | +export type NormalizedPrOutcomePayload = { |
| 8 | + prNumber: number; |
| 9 | + decision: MinerPrOutcomeDecision; |
| 10 | + closedAt: string | null; |
| 11 | + reason: string | null; |
| 12 | +}; |
| 13 | +export type PrOutcomeInput = { |
| 14 | + repoFullName?: unknown; |
| 15 | + prNumber?: unknown; |
| 16 | + decision?: unknown; |
| 17 | + closedAt?: unknown; |
| 18 | + reason?: unknown; |
| 19 | +}; |
| 20 | +export type RecordPrOutcomeOptions = { |
| 21 | + /** Optional at the type level so a caller can pass an unusable ledger to exercise the fail-closed guard; the |
| 22 | + * writer throws `invalid_event_ledger` at runtime when this is absent or lacks `appendEvent`. Reuses the |
| 23 | + * real EventLedger#appendEvent signature so a genuine EventLedger (not just a same-shaped stub) type-checks. */ |
| 24 | + eventLedger?: { |
| 25 | + appendEvent(event: AppendEventInput): LedgerEntry; |
| 26 | + }; |
| 27 | +}; |
| 28 | +export type PrOutcomeLedgerReader = { |
| 29 | + readEvents(filter?: { |
| 30 | + since?: number; |
| 31 | + repoFullName?: string; |
| 32 | + }): unknown[]; |
| 33 | +}; |
| 34 | +/** |
| 35 | + * Validate + normalize a PR-outcome payload; returns `null` on any malformed shape (mirrors manage-status.js's |
| 36 | + * `normalizeManageUpdatePayload`, so a bad row can neither be written nor read back). A `closed` decision may carry |
| 37 | + * a reason bucket drawn from {@link REJECTION_REASONS} (shared with the rejection-state-machine sibling); a `merged` |
| 38 | + * decision — or an unrecognized reason — normalizes the reason to `null` (a merged PR has no rejection reason). |
| 39 | + */ |
| 40 | +export declare function normalizePrOutcomePayload(payload: unknown): NormalizedPrOutcomePayload | null; |
| 41 | +/** |
| 42 | + * Thin writer over an INJECTED event ledger (same dependency-injection shape as manage-poll.js's |
| 43 | + * `recordManagePollSnapshot`, so it's unit-testable without a real ledger file). Appends one |
| 44 | + * {@link MINER_PR_OUTCOME_EVENT} scoped to the repo and returns the appended entry. Fail-soft on a malformed |
| 45 | + * snapshot: a missing repo or an invalid payload returns `null` rather than throwing (an unusable ledger is the |
| 46 | + * only hard error, since that is a programmer wiring mistake). |
| 47 | + */ |
| 48 | +export declare function recordPrOutcomeSnapshot(input: PrOutcomeInput, options?: RecordPrOutcomeOptions): unknown; |
| 49 | +/** |
| 50 | + * Reconstruct the latest outcome per repo/PR from the ledger's ascending append-only event stream (mirrors |
| 51 | + * manage-status.js's `indexLatestManageUpdates`). Reads via the injected ledger's `readEvents(filter)` and reduces |
| 52 | + * the pure result — a later event for the same repo/PR supersedes an earlier one. Returns a `Map` keyed by |
| 53 | + * `repoFullName:prNumber`. |
| 54 | + */ |
| 55 | +export declare function readPrOutcomes(eventLedger: PrOutcomeLedgerReader | null | undefined, filter?: { |
| 56 | + since?: number; |
| 57 | + repoFullName?: string; |
| 58 | +}): Map<string, NormalizedPrOutcomePayload & { |
| 59 | + repoFullName: string; |
| 60 | +}>; |
0 commit comments