@ashlr/hub 3.12.0 → 3.13.0

package/dist/core/cloud/timeline.d.ts

@@ -0,0 +1,102 @@
+import { readLedger } from '../authority/ledger.js';
+import { readFleetMergeState, type FleetMergeStateV1 } from '../fleet/fleet-merge-state.js';
+import type { GateResult, LandingRecord, PostMergeResult } from '../fleet/fleet-types.js';
+import { type PostMergeWatchView } from '../fleet/post-merge-watch.js';
+import { type GitRunner } from '../verse/git-ops.js';
+import { type CloudTimelineResponse } from './timeline-types.js';
+import { type CloudTaskV1 } from './types.js';
+export type MergeRecordSource = {
+    state: 'ok';
+    record: FleetMergeStateV1;
+} | {
+    state: 'missing';
+} | {
+    state: 'unknown';
+    reason: string;
+};
+export type LedgerSource = {
+    state: 'ok';
+    /** `ok` = chain verified; `empty` = no ledger yet. */
+    chain: 'ok' | 'empty';
+    gates: Array<GateResult & {
+        rowAt: string;
+    }>;
+    landing: LandingRecord | null;
+    postMerge: PostMergeResult | null;
+} | {
+    state: 'unknown';
+    reason: string;
+};
+export type WatchSource = {
+    state: 'ok';
+    view: PostMergeWatchView | null;
+} | {
+    state: 'unknown';
+    reason: string;
+};
+export interface MergeCommit {
+    sha: string;
+    /** `landing` = our host merge recorded it; `git` = found by message in local git. */
+    basis: 'landing' | 'git';
+}
+export type ReleaseSource = {
+    state: 'contained';
+    latestTag: string;
+    firstTag: string | null;
+} | {
+    state: 'not-contained';
+    latestTag: string;
+} | {
+    state: 'no-tags';
+} | {
+    state: 'unknown';
+    reason: string;
+};
+export interface TimelineSources {
+    task: CloudTaskV1;
+    merge: MergeRecordSource;
+    ledger: LedgerSource;
+    watch: WatchSource;
+    /** The producing model from the evidence pack; null = not recorded. */
+    model: string | null;
+    mergeCommit: MergeCommit | null;
+    /** Null when there is no merge commit to look for. */
+    release: ReleaseSource | null;
+}
+/** PURE: the ordered evidence chain for one task from already-gathered sources. */
+export declare function buildCloudTimeline(sources: TimelineSources, now?: Date): CloudTimelineResponse;
+export interface TimelineDeps {
+    now?: () => Date;
+    readTask?: (id: string) => CloudTaskV1 | null;
+    /** Every merge record key (null = directory unreadable). */
+    listMergeKeys?: () => string[] | null;
+    readMergeRecord?: typeof readFleetMergeState;
+    readLedger?: typeof readLedger;
+    listWatches?: () => PostMergeWatchView[];
+    readEvidenceModel?: (proposalId: string) => string | null;
+    git?: GitRunner;
+    /** A local clone of `repo` with its tags (fleet mirror, else an enrolled checkout); null = none. */
+    checkoutFor?: (repo: string) => Promise<string | null>;
+    /** Time budget for the ledger read (default 2.5 s). */
+    ledgerBudgetMs?: number;
+    /** Time budget for every git step together (default 5 s). */
+    gitBudgetMs?: number;
+}
+/** Test hook: drop every cache (the merge index, git answers, checkouts, whole timelines). */
+export declare function clearCloudTimelineCaches(): void;
+/** `owner/name` of a GitHub remote URL (https, ssh, scp-style), lowercased; null otherwise. */
+export declare function githubNameFromRemote(url: string): string | null;
+/** Production checkout finder: the fleet mirror, else an enrolled project whose origin is `repo`. */
+export declare function defaultCheckoutFor(git: GitRunner): (repo: string) => Promise<string | null>;
+/** Gather every source for one task. Never throws; a failing source becomes 'unknown'. */
+export declare function gatherTimelineSources(task: CloudTaskV1, deps?: TimelineDeps): Promise<TimelineSources>;
+/** Test hook: the sources the HTTP route reads (null restores production). Clears every cache. */
+export declare function setCloudTimelineDepsForTest(deps: TimelineDeps | null): void;
+/** What timeline-api.ts passes to cloudTaskTimeline (production: real stores and git). */
+export declare function timelineDepsForRoute(): TimelineDeps;
+/**
+ * The timeline for task `id`, or null when there is no such task. Cached per
+ * task revision (`updatedAt`) for a few seconds, and concurrent requests for
+ * one task share a single gather.
+ */
+export declare function cloudTaskTimeline(id: string, deps?: TimelineDeps): Promise<CloudTimelineResponse | null>;