gatelineAPI reference
interface RunObservation {
    artifacts: string[];
    bounceCounts: Record<string, number>;
    declineEvents: Partial<
        Record<
            "G0"
            | "G1"
            | "G2"
            | "G3",
            { at: number; notes: null | string; redone: boolean },
        >,
    >;
    enforceBudget: boolean;
    estimates: Record<string, number>;
    idleDispatches: Map<string, number>;
    inFlightSurfaces: string[][];
    lastNonStateCommit: null | number;
    lastNonStateOid: null | string;
    lastTouched: Record<string, null | number>;
    lastTouchedOid: Record<string, null | string>;
    ledger: BudgetLedgerEntry[];
    ledgerCommits: { close: null | CommitInfo; open: null | CommitInfo }[];
    ledgerSpentUsd: number;
    openDispatches: OpenDispatch[];
    order: BranchOrder;
    resolutionCommits: (null | CommitInfo)[];
    reviews: ReviewInfo[];
    slug: string;
    state:
        | null
        | {
            branch: string;
            budget: | null
            | {
                cost_limit_usd: null
                | number;
                cost_spent_usd: null | number;
                [key: string]: unknown;
            };
            closure: | null
            | {
                as: "already-delivered"
                | "superseded"
                | "obsolete"
                | "abandoned";
                at: null | string;
                by: null | string;
                reason: null | string;
                [key: string]: unknown;
            };
            escalations: {
                at: null
                | string;
                disposition: null | "re-review" | "return-to-implement" | "re-plan";
                from_role: null | string;
                reason: string;
                resolution: null | string;
                resolved: boolean;
                resolved_at: null | string;
                resolved_by: null | string;
                [key: string]: unknown;
            }[];
            gates: {
                G0: {
                    approved: boolean;
                    at: null
                    | string;
                    burden: null | "confirmation" | "light-correction" | "heavy-correction";
                    by: null | string;
                    notes: null | string;
                    [key: string]: unknown;
                };
                G1: {
                    approved: boolean;
                    at: null
                    | string;
                    burden: null | "confirmation" | "light-correction" | "heavy-correction";
                    by: null | string;
                    notes: null | string;
                    [key: string]: unknown;
                };
                G2: {
                    approved: boolean;
                    at: null
                    | string;
                    burden: null | "confirmation" | "light-correction" | "heavy-correction";
                    by: null | string;
                    notes: null | string;
                    [key: string]: unknown;
                };
                G3: {
                    approved: boolean;
                    at: null
                    | string;
                    burden: null | "confirmation" | "light-correction" | "heavy-correction";
                    by: null | string;
                    notes: null | string;
                    [key: string]: unknown;
                };
            };
            paused_reason: null
            | string;
            phase:
                | "spec"
                | "plan"
                | "implement"
                | "integrate"
                | "release"
                | "done"
                | "paused"
                | "closed";
            profile: "patch"
            | "standard"
            | "full";
            run: string;
            tasks: {
                id: string;
                review_rounds: number;
                status: string;
                [key: string]: unknown;
            }[];
        };
    stateError: null
    | string;
    taskFiles: Map<string, TaskFileInfo>;
    validations: Record<string, Validation>;
    verification: null | VerificationInfo;
}

Properties

artifacts: string[]
bounceCounts: Record<string, number>

Artifact → orchestrator bounce commits since the artifact's bounce budget last reset, from the commit grammar.

The budget is per dispute, not per lifetime (#348). Counting the whole branch history made D8 a one-shot: a human who resolved the contract dispute, repaired the artifact by hand and let the producer regenerate it got no bounces at all the next time it came back malformed — the second occurrence escalated on sight, with a reason quoting bounces from weeks earlier. Resolving the D8 escalation for an artifact is what clears its count, so each dispute starts the same two bounces the first one had.

declineEvents: Partial<
    Record<
        "G0"
        | "G1"
        | "G2"
        | "G3",
        { at: number; notes: null | string; redone: boolean },
    >,
>

Most recent decline per gate, from state history (survives resume resets). redone is true once the gate's packet artifact has landed again after the decline — decided by commit ancestry when available, commit time otherwise (same-second commits make wall clocks ambiguous).

enforceBudget: boolean

Whether budget caps pause dispatch (#109). Orchestrator config injected like estimates, defaulting on; when off, DB never fires — metering (ledger, ledgerSpentUsd) is unconditional either way.

estimates: Record<string, number>

Static per-role estimates from the registry (resolved question 2).

idleDispatches: Map<string, number>

Per (role, task) — keyed by idleKey — how many dispatches closed ok and landed nothing (#343): closed-ok ledger entries opened after the last commit touching what that dispatch existed to produce — the gate's packet artifact for a producer, the task's whole record for a task-scoped role. Rule DL reads it before every dispatch, because half the derivation table re-dispatches on the absence of an expected change and would otherwise count nothing at all — an agent that returns ok and commits nothing is a success to the close path and a no-op here, so the same dispatch re-derives every tick until the budget stops it.

The count resets on two facts: what it was to land moving (the role produced), and a human resolving that (role, task)'s escalation — the same "resolution newer than the standing fact" shape D17 and D20 read, so resolve-and-resume does not walk straight back into the cap.

inFlightSurfaces: string[][]

file_contact_surfaces of tasks currently being worked (not pending, not complete).

lastNonStateCommit: null | number

Epoch seconds of the newest run-branch commit touching anything other than state.yaml (#188) — the delta guard for D17's post-resolution re-review: a resolution commit only ever edits state.yaml itself, so without this a re-review round can dispatch against a byte-identical range and burn a capped round for nothing.

lastNonStateOid: null | string

That same commit's oid (#346).

lastTouched: Record<string, null | number>

Run-relative path → newest commit epoch seconds touching it.

lastTouchedOid: Record<string, null | string>

Run-relative path → oid of that same commit, for the branch-order comparisons (#346).

ledgerCommits: { close: null | CommitInfo; open: null | CommitInfo }[]

Per ledger entry (same index as ledger), the state commits that opened and closed it — the dispatch's intent commit and the one that recorded its outcome. The landing cap counts by the first and rule D20 reads the second, both by branch order rather than by the engine host's clock.

ledgerSpentUsd: number

Sum of closed ledger cost, or cost_spent_usd when no ledger exists (v0 runs).

openDispatches: OpenDispatch[]

Ledger entries opened by a dispatch and not yet closed: in-flight work.

The run branch's own order over its commits (#346) — what "after" means once the three clocks that stamp these facts are allowed to disagree.

resolutionCommits: (null | CommitInfo)[]

Per escalation index, the state commit in which resolved became true, or null when the history does not show the flip. This, not resolved_at, is when a human resolved something: resolved_at is stamped by whichever machine served the decision, and the documented topology puts that machine somewhere else entirely (#346).

reviews: ReviewInfo[]
slug: string
state:
    | null
    | {
        branch: string;
        budget: | null
        | {
            cost_limit_usd: null
            | number;
            cost_spent_usd: null | number;
            [key: string]: unknown;
        };
        closure: | null
        | {
            as: "already-delivered"
            | "superseded"
            | "obsolete"
            | "abandoned";
            at: null | string;
            by: null | string;
            reason: null | string;
            [key: string]: unknown;
        };
        escalations: {
            at: null
            | string;
            disposition: null | "re-review" | "return-to-implement" | "re-plan";
            from_role: null | string;
            reason: string;
            resolution: null | string;
            resolved: boolean;
            resolved_at: null | string;
            resolved_by: null | string;
            [key: string]: unknown;
        }[];
        gates: {
            G0: {
                approved: boolean;
                at: null
                | string;
                burden: null | "confirmation" | "light-correction" | "heavy-correction";
                by: null | string;
                notes: null | string;
                [key: string]: unknown;
            };
            G1: {
                approved: boolean;
                at: null
                | string;
                burden: null | "confirmation" | "light-correction" | "heavy-correction";
                by: null | string;
                notes: null | string;
                [key: string]: unknown;
            };
            G2: {
                approved: boolean;
                at: null
                | string;
                burden: null | "confirmation" | "light-correction" | "heavy-correction";
                by: null | string;
                notes: null | string;
                [key: string]: unknown;
            };
            G3: {
                approved: boolean;
                at: null
                | string;
                burden: null | "confirmation" | "light-correction" | "heavy-correction";
                by: null | string;
                notes: null | string;
                [key: string]: unknown;
            };
        };
        paused_reason: null
        | string;
        phase:
            | "spec"
            | "plan"
            | "implement"
            | "integrate"
            | "release"
            | "done"
            | "paused"
            | "closed";
        profile: "patch"
        | "standard"
        | "full";
        run: string;
        tasks: {
            id: string;
            review_rounds: number;
            status: string;
            [key: string]: unknown;
        }[];
    }
stateError: null | string
taskFiles: Map<string, TaskFileInfo>
validations: Record<string, Validation>

Validation per contract-bound artifact present in the run.

verification: null | VerificationInfo

The verification report's overall verdict (#152), or null when the run has no report.