From 18d7afb5a2ac3253e323b49528dd50be670e102a Mon Sep 17 00:00:00 2001 From: Graeme Foster <80714+GraemeF@users.noreply.github.com> Date: Tue, 27 Oct 2026 11:45:45 +0000 Subject: [PATCH] docs(berth): state the contract outside products may rely on --- docs/design.md | 9 +++++++++ tests/berth-contract | 1 + 2 files changed, 10 insertions(+) diff --git a/docs/design.md b/docs/design.md index 3f0736c..1338da7 100644 --- a/docs/design.md +++ b/docs/design.md @@ -101,6 +101,15 @@ A caller that is not itself a berth has none of the three: a service manager's u Where a verb needs the caller, such as a worker's opener or the opener a berth opens beside, the calling pane stands in for a caller that is not a berth. It stands in only within its own yard. A caller in no pane, or whose pane is in another yard than the one named, is refused with a message that says which. +### Contract for outside consumers + +A product outside boatyard may depend on two things, and on nothing else of boatyard's: + +- **The three variables** above, inherited by every process a berth runs. +- **`berth list`'s JSON:** an array with one object per berth, each holding exactly the fields `id`, `label`, `relationship`, `parent`, `state`, `agent_state` and `agent_session`, with the values the verbs table and *Berth and agent states* give them. + +Dropping, renaming or changing the meaning of a variable or a field breaks the contract, and so does a new value that a consumer could not have expected. Boatyard cuts no releases, so the pull request making such a change marks it breaking with a `!` in its title, and the commit it lands as carries the mark on `main`. The port contract suite fails when a field is added, dropped or renamed, so no change to the shape lands unnoticed. + ### Errors - A berth that no longer exists reports state `gone`, and agent state `none`, and exits 0. That is an answer, not a failure. diff --git a/tests/berth-contract b/tests/berth-contract index 22156f6..8c04c2a 100755 --- a/tests/berth-contract +++ b/tests/berth-contract @@ -77,6 +77,7 @@ check "a worker is listed as a worker" worker "$(field "$worker" relationship)" check "a worker's parent is its opener" "$independent" "$(field "$worker" parent)" check "a worker's command learns its own BERTH_ID" "$worker" "$(recorded "$work/worker" BERTH_ID)" check "a worker inherits BERTH_YARD" "$BERTH_YARD" "$(recorded "$work/worker" BERTH_YARD)" +check "a worker inherits BERTH_BACKEND" "$BERTH_BACKEND" "$(recorded "$work/worker" BERTH_BACKEND)" second_worker=$(BERTH_ID=$independent berth open --as worker --cwd "$work" -- true) check "a second worker has the same parent" "$independent" "$(field "$second_worker" parent)"