gatelineAPI reference

Interface RunSource

interface RunSource {
    id: string;
    templates: ContractTemplates;
    aheadOfOrigin(ref: RunRef): Promise<null | number>;
    behindOrigin(ref: RunRef): Promise<null | number>;
    identity(): Promise<null | Identity>;
    lastTouched(ref: RunRef, paths: string[]): Promise<null | CommitInfo>;
    lastTouchedExcept(
        ref: RunRef,
        excludePaths: string[],
    ): Promise<null | CommitInfo>;
    listArtifacts(ref: RunRef): Promise<string[]>;
    listRuns(): Promise<RunRef[]>;
    originUrl(): Promise<null | string>;
    readArtifact(ref: RunRef, path: string): Promise<null | string>;
    readDiff(ref: RunRef): Promise<string>;
    readState(ref: RunRef): Promise<StateParseResult & { raw: null | string }>;
    runHistory(ref: RunRef): Promise<CommitInfo[]>;
    stageRun(scaffold: RunScaffold, who: Identity): Promise<StageOutcome>;
    stateHistory(ref: RunRef): Promise<StateCommit[]>;
    writeState(
        ref: RunRef,
        mutate: StateDocMutation,
        message: string,
        options?: { expectedTip?: string },
    ): Promise<WriteResult>;
}

Implemented by

Properties

id templates

Methods

aheadOfOrigin? behindOrigin? identity lastTouched lastTouchedExcept listArtifacts listRuns originUrl? readArtifact readDiff readState runHistory? stageRun stateHistory writeState

Properties

Readonlyid

id: string

Readonlytemplates

templates: ContractTemplates

Contract templates of this repo, for R3 validation.

Methods

OptionalaheadOfOrigin

  • aheadOfOrigin(ref: RunRef): Promise<null | number>

    Commits on the run branch that origin does not yet have — unpushed writes (#149): the lineage Gatehouse renders and the lineage origin consumers see have silently diverged. Absent method or null result means "not knowable" (no origin tracking, remote-kind run) — display nothing, never zero.

    Parameters

    Returns Promise<null | number>

OptionalbehindOrigin

  • behindOrigin(ref: RunRef): Promise<null | number>

    Commits origin has that the local run branch does not (#99). Non-zero together with aheadOfOrigin means the branch has genuinely diverged — local-wins observation is then a deliberate choice that must be visible, never silent. Absent method or null means "not knowable".

    Parameters

    Returns Promise<null | number>

identity

lastTouched

lastTouchedExcept

  • lastTouchedExcept(
        ref: RunRef,
        excludePaths: string[],
    ): Promise<null | CommitInfo>

    Most recent commit touching anything in the run directory except the given run-relative paths — the delta guard (#188): state.yaml alone moving (bookkeeping, a resolution note) is not "something landed".

    Parameters

    • ref: RunRef
    • excludePaths: string[]

    Returns Promise<null | CommitInfo>

listArtifacts

listRuns

OptionaloriginUrl

  • originUrl(): Promise<null | string>

    This source's remote.origin.url, verbatim, for deriving a link out to the git host (#267 — view-model/host-link.ts decides what it means). Null means there is nothing to link to and the caller keeps its local view: no remote configured, or a local-only source, which has no origin by definition (FRONTEND.md §4.1 — degrade to the local view, never to a dead end). Absent method means the same.

    Returns Promise<null | string>

readArtifact

readDiff

readState

OptionalrunHistory

  • runHistory(ref: RunRef): Promise<CommitInfo[]>

    Every commit on the run branch touching the run's own directory, newest first — the branch's own order, which is what "after" means when the clocks that stamped the facts disagree (#346, branch-order.ts). One log, no per-commit reads: stateHistory is the expensive walk, this is the cheap index that places its commits alongside the artifact landings.

    Optional, like the origin-divergence counts: a driver with no history to offer omits it, and its callers fall back to timestamps.

    Parameters

    Returns Promise<CommitInfo[]>

stageRun

  • stageRun(scaffold: RunScaffold, who: Identity): Promise<StageOutcome>

    The only branch-minting path (plan ADR-3, R1): builds a genesis commit from scaffold.files against the default branch's tip and lands it via create-only CAS. Always authored as who — never a bot-pinned source identity — because a staged run must be attributable to the human who staged it, whoever is holding the write path.

    Parameters

    Returns Promise<StageOutcome>

stateHistory

writeState

  • writeState(
        ref: RunRef,
        mutate: StateDocMutation,
        message: string,
        options?: { expectedTip?: string },
    ): Promise<WriteResult>

    The single write path (rule R2): apply a mutation to state.yaml and commit it to the run branch, compare-and-swap semantics. expectedTip extends the CAS window back to the caller's read: when given and the branch no longer points there, the write refuses with ref-moved — the machine co-writer's derive-then-write guard (ORCHESTRATOR.md §4.4). Human surfaces omit it: their reads happen inside this call.

    Parameters

    Returns Promise<WriteResult>

Settings

Member Visibility

On This Page

Properties
Methods