Skip to content

feat(contract): berth contract ENGINE shows one engine's terms - #321

Merged
T-Crypt merged 1 commit into
nextfrom
T-Crypt/berth-contract
Nov 13, 2026
Merged

T-Crypt merged 1 commit into
nextfrom
T-Crypt/berth-contract

Conversation

@T-Crypt

@T-Crypt T-Crypt commented Nov 13, 2026

Copy link
Copy Markdown
Owner

Why

Berth Next milestone 1c. The numbers that decide whether an engine fits are spread over three places today:
berth.toml, the broker's footprint book and the gateway's switch book. None of them says how far its number can be
trusted. Fit (milestone 2) needs those numbers in one place, each with its source. People need the same view when
they ask why a lease got the size it got.

What changes

  • New package internal/contract. Build(name, *config.Engine, *proto.Status, *swapcost.Book) is pure and
    returns a Contract. Every number is a typed value with a source:

    • declared: berth.toml sets it.
    • default: berth.toml is silent, so Berth's default applies.
    • measured: from the footprint or switch book.
    • unknown: nothing declares it and nothing measured it.

    VRAM follows the broker's rule. It is needs_mib if set (the largest card's value for a per-card list). With
    learn_size it is the measured peak plus 512 MiB, or the whole card when the peak fills it or was never
    measured. Otherwise it is the whole card.

  • berth contract ENGINE [--config] [--costs] [--socket] [--format]. ENGINE can be an [[engine]] name, a
    discovered engine, or a llama-swap model's --as name. Without berthd it prints the declared terms and marks
    every measured number unknown.

  • proto.EngineFootprint gains hot_peak_vram_bytes, ram_peak_bytes and parked_ram_bytes (all omitempty).
    footprintStatus now keeps an entry that holds only those figures. A llama-swap model's own peak sits on its
    name's entry and its last run on the group's, so the model's own entry was dropped before. berth status EST.
    VRAM ignores a zero estimated_vram_bytes, the same way the harbor already did.

A contract is a view with no file of its own, as the plan decided, so it cannot drift from berth.toml.

Proof

  • TestBuildVRAM covers 8 sizing cases with literal sizes and reasons. TestBuildMeasuredAndDeclared and
    TestBuildSwitch check the median of three samples, that hot is free by rule, and that a tier with no samples
    is unknown.
  • TestFootprintStatusCarriesAModelsOwnPeak runs a real broker lease in group llama-swap. It fails with the old
    Last == 0 filter (the model's entry is missing) and passes with the fix.
  • TestContractWithoutBerthd covers the CLI JSON and human output, an unknown name, and flags after ENGINE.
    Writing it showed that Parse stopped at the positional argument, so the command now uses ParseInterspersed.
  • Against the live berthd on aphotic (an older build): berth contract comfyui shows priority foreground
    (declared), last peak 456 MiB (measured, 146 runs) and cold switch 8.0 s (median of 20).
    berth contract strata shows min turn 5m (declared) and cold switch 73.0 s.
  • proof.sh full passes.

Not yet live: a llama-swap model's name (Dirk-27B) shows up once aphotic runs this build. A training run holds
the card right now, so berthd cannot restart.

One engine's terms in one place, each number tagged with where it came
from: declared in berth.toml, Berth's default, measured, or unknown. It
covers the priority, the VRAM a lease asks for (needs_mib, the learn_size
size the broker would grant, or the whole card), the last run's peak, the
RAM a run needs and holds parked, the minimum turn and window, and the
gateway's median switch time per tier.

A contract is a view over [[engine]] and berthd's status, with no file of
its own, so it cannot drift from the config. Fit reads the same view next.

The status reply's footprints now carry hot_peak_vram_bytes,
ram_peak_bytes and parked_ram_bytes, and keep an entry that holds only
those. A llama-swap model's own peak sits on its name's entry while the
last run sits on the group's, so the model's entry was dropped before.
@T-Crypt
T-Crypt merged commit a7eb6f2 into next Nov 13, 2026
4 checks passed
@T-Crypt
T-Crypt deleted the T-Crypt/berth-contract branch November 13, 2026 14:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant