packages/forkhorse-stable/src/records.ts

1/** Public wire records mirrored from core; drift is checked against core declarations. */
2export interface Project {
3  id: string;
4  namespace: string;
5  repoName: string;
6  remote: string;
7  defaultBranch: string;
8  /** Missing on legacy records: effective default is false until owner opts in. */
9  settings?: { requireReceipt: boolean };
10}
11
12export interface Activity {
13  sequence: number;
14  namespace: string;
15  repoName: string;
16  agent: string | null;
17  ref: string;
18  before: string;
19  after: string;
20  changedPaths: string[];
21  changedPathCount: number;
22  changedPathsTruncated: boolean;
23  eventTimestamp: string;
24  recordedAt: string;
25}
26/** Persistent public workflow records; none contain Git/API credentials. */
27export interface Packet {
28  id: string;
29  /** Absent only in legacy storage; public reads normalize it to standard. */
30  mode?: "standard" | "race";
31  /** Immutable race-only limit on input plus output tokens. */
32  tokenBudget?: number;
33  title: string;
34  goal: string;
35  paths: string[];
36  acceptance: string[];
37  archived: null | { at: string; by: "owner" };
38}
39/** Durable owner audit; Git-push Activity records retain their existing schema. */
40export interface PacketArchiveAudit {
41  packet: string;
42  action: "archive" | "unarchive";
43  by: "owner";
44  recordedAt: string;
45}
46export interface Fork {
47  repoName: string;
48  agent: string;
49  remote: string;
50  createdAt: string;
51}
52export interface Claim {
53  packet: string;
54  agent: string;
55  repoName: string;
56  paths: string[];
57  createdAt: string;
58  /** Absent only in legacy storage; public reads normalize both sources to null. */
59  usage?: UsageSources;
60}
61export interface Usage {
62  inputTokens: number;
63  outputTokens: number;
64  model?: string;
65  source: "reported" | "metered";
66  at: string;
67}
68export interface UsageSources {
69  reported: Usage | null;
70  metered: Usage | null;
71}
72export type TokenBudgetState = "unchecked" | "within" | "near" | "over";
73/** Race history is retained at entrant:<packet>:<agent>, including after release. */
74export interface RaceEntrant extends Claim {
75  firstPushAt: string | null;
76  reviewRequestedAt: string | null;
77  receiptPassedAt: string | null;
78  approvedAt: string | null;
79  promotedAt: string | null;
80  place: number | null;
81  closedAt: string | null;
82  closedBy: "release" | "owner" | "race-finished" | null;
83  /** Absent on older entrants; the first canonical-base refusal is retained. */
84  promoteRejected?: { at: string; expected: string; found: string } | null;
85}
86/** Immutable finish at race:<packet>; places name agents, never fork aliases. */
87export interface RaceResult {
88  winner: string;
89  places: { agent: string; place: number }[];
90  finishedAt: string;
91  ledgerEntryId: string;
92}
93export interface RaceVerdict {
94  ranking: string[];
95  rationale: string;
96  at: string;
97}
98export interface RaceState {
99  packet: string;
100  judge: string | null;
101  verdict: RaceVerdict | null;
102  tokenBudget: number | null;
103  status: "open" | "finished";
104  finishedAt: string | null;
105  winner: string | null;
106  ledgerEntryId: string | null;
107  places: RaceResult["places"];
108  entrants: (Omit<RaceEntrant, "packet" | "paths" | "createdAt"> & {
109    claimedAt: string; usage: UsageSources; budget: TokenBudgetState;
110  })[];
111}
112/** Durable release history. Claim identity and provenance only; no credentials. */
113export interface ClaimReleaseAudit {
114  packet: string;
115  agent: string;
116  repoName: string;
117  claimedAt: string;
118  releasedBy: "agent" | "owner" | "promote" | "race-finished";
119  review?: string;
120  recordedAt: string;
121}
122export interface ReceiptSummary {
123  status: "running" | "passed" | "failed" | "infrastructure-error" | "timed-out";
124  trigger: "review-created" | "before-promote";
125  digest: string | null;
126  startedAt: string;
127  finishedAt: string | null;
128  durationMs: number | null;
129  checks: { name: string; tier: "full" | "quick"; runtime?: "container" | "dynamic-worker"; message?: string; outcome: ReceiptSummary["status"]; durationMs: number | null }[];
130}
131export interface Review {
132  id: string;
133  packet: string;
134  agent: string;
135  repoName: string;
136  sha: string;
137  base: string;
138  receiptDigest: string | null;
139  receipt: ReceiptSummary | null;
140  approval: { sha: string; receiptDigest: string | null } | null;
141  stale: boolean;
142  promoted: boolean;
143  returned: null | { reason: string; at: string };
144  createdAt: string;
145  /** Immutable cumulative snapshot; absent only in legacy storage. */
146  usageAtReview: UsageSources;
147}
148/** Caller-owned live work only; review execution identities and credentials are omitted. */
149export interface WorkItem {
150  packet: Pick<Packet, "id" | "title">;
151  repoName: string;
152  claimedAt: string;
153  forkHead: string;
154  canonicalHead: string;
155  review:
156    | null
157    | (Pick<Review, "id" | "sha" | "stale" | "returned" | "promoted"> & {
158        receipt: ReceiptSummary | null;
159        approved: boolean;
160      });
161  next:
162    | "push"
163    | "request_review"
164    | "wait_for_checks"
165    | "fix_checks"
166    | "address_return"
167    | "wait_for_owner"
168    | "done";
169  hint: string;
170}
171export interface LedgerEntry {
172  id: string;
173  review: string;
174  repoName: string;
175  ref: string;
176  before: string;
177  after: string;
178  receiptDigest: string | null;
179  /** Gate used by this promotion; absent on legacy entries whose policy is unknown. */
180  requireReceipt?: boolean;
181  recordedAt: string;
182  /** Packet ID linking this promotion to race:<packet>; absent on standard entries. */
183  race?: string;
184}
185export interface SettingsChange {
186  setting: "requireReceipt";
187  before: boolean;
188  after: boolean;
189  by: "owner";
190  via: "access" | "owner-api";
191  recordedAt: string;
192}
193export interface Blocker {
194  id: string;
195  packet: string;
196  claimingAgent: string;
197  pushingAgent: string;
198  repoName: string;
199  sha: string;
200  paths: string[];
201  at: string | null;
202  pushingPacket: string | null;
203  resolved: null | { at: string; by: "release" | "promote" | "owner" | "race-finished"; reason?: string };
204}
205export interface ReconcilerAlert {
206  id: string;
207  repoName: string;
208  ref: string;
209  before: string;
210  after: string;
211  reason: string;
212}
213export interface CommitFile {
214  path: string;
215  content: string;
216}
217
218/** Authenticated dashboard/MCP snapshot. Arrays contain public records only. */
219export interface StateSnapshot {
220  project: Project & { settings: { requireReceipt: boolean } };
221  agents: { name: string; createdAt: string | null }[];
222  forks: (Fork & { head: string })[];
223  packets: Packet[];
224  /** Only live claims appear. Release removes the claim, but keeps historical reviews. */
225  claims: (Claim & { usage: UsageSources })[];
226  races: RaceState[];
227  blockers: Blocker[];
228  reviews: (Review & { receipt: ReceiptSummary | null; usageAtReview: UsageSources })[];
229  ledger: LedgerEntry[];
230  /** Actual owner changes only; legacy policy is never backfilled. */
231  settingsChanges: SettingsChange[];
232  /** Most recent 100 entries in ascending receive sequence. */
233  activity: Activity[];
234  reconcilerAlerts: ReconcilerAlert[];
235  /** A durable intent whose external outcome needs inspection; never an applied merge. */
236  promotionPending: LedgerEntry | null;
237}
238