Plumb

Specification

dev07-6 · append the run to the series

A sub-flow of dev07 · run plumb. Entered where the project keeps a series, carrying the run's verdicts. Exits with the run in the history and the history readable: closing a session compares against it, and a reader asks it when.

3 of 5 stories proven · 0 passed, not wired · 0 unproven · 2 with nothing holding them

dev07-6-1 append what changed Proven

As a developer asking when this broke I want every run to leave its mark in a history, so that the questions one run cannot answer have somewhere to be answered from.

The tests that cite it (11)
  • tests/test_end_to_end.py::test_a_board_read_from_a_manifest_appends_to_the_series — passed, grounded
  • tests/test_end_to_end.py::test_a_board_printed_as_json_still_appends_to_the_series — passed, grounded
  • tests/test_series.py::test_a_line_a_reader_cannot_make_a_record_of_is_refused_by_name — passed, ungrounded
  • tests/test_series.py::test_a_line_that_is_not_json_says_so_at_its_own_line_number — passed, ungrounded
  • tests/test_series.py::test_an_unreadable_store_is_an_outcome_and_never_a_traceback — passed, ungrounded
  • tests/test_series.py::test_reading_a_broken_store_through_the_command_says_which_line — passed, grounded
  • tests/test_series.py::test_a_series_is_stamped_once_when_it_is_created — passed, ungrounded
  • tests/test_series.py::test_two_series_are_stamped_differently — passed, ungrounded
  • tests/test_series.py::test_a_history_carrying_no_stamp_is_of_unknown_extent — passed, ungrounded
  • tests/test_series.py::test_show_says_unknown_extent_rather_than_reporting_a_short_history — passed, grounded
  • tests/test_series.py::test_the_origin_survives_compaction — passed, ungrounded
Requirements (12)
What the user needs
  • dev07-6-1-ur1the series accumulates what changed and never what stayed the same — an unchanged run writes no transition
  • dev07-6-1-ur2a marker is written for every run whether or not anything changed, so nothing moved and nobody looked stay different answers
  • dev07-6-1-ur3a fact that disappears is recorded as gone — absence is a transition, never a silent stop
  • dev07-6-1-ur4the origin is stamped when the series is created; a history carrying no stamp is reported as one of unknown extent, never as a short one
  • dev07-6-1-ur5an entry that cannot be read is refused, saying where it is and what shape it has; an unreadable history is an outcome the run reports, never a crash
  • dev07-6-1-ur6a run told to keep a series appends to it however its board is printed — a board printed for a machine is the same run as one printed for a person
What the system does
  • dev07-6-1-sr1a history kept in the project's own tree is append-only, and transitions, run markers and records of discard share one order, because the ordering between them is the point
  • dev07-6-1-sr2the sequence is dense and monotonic, so a jump with no record of discard beside it means a record was lost rather than let go
  • dev07-6-1-sr3what a fact cost rides as payload and never decides a transition — a duration moves every run, and admitting it would write an entry per citation per run
  • dev07-6-1-sr4the origin stamp is generated and never recomputed — a stamp that could be recomputed after a loss would prove nothing about surviving one
How well
  • dev07-6-1-nfr1a history reports and never grades
Still open
  • dev07-6-1-u1nothing bounds a store, and nothing has measured what a series costs to keep; what is measurable now is what a run emits — bytes per transition at a real cadence

dev07-6-2 hand the history to its holder Proven

As an adopter whose history outgrows one machine I want it held for me and handed back, so that the history is custodial — mine, kept elsewhere, returned.

The tests that cite it (28)
  • tests/test_account_client.py::test_what_would_be_sent_carries_the_adopters_names_as_written — passed, ungrounded
  • tests/test_capture.py::test_a_series_is_held_and_handed_back — passed, dispatched
  • tests/test_capture.py::test_a_discarded_range_comes_back_as_discarded_and_never_as_a_gap — passed, dispatched
  • tests/test_capture.py::test_never_held_and_emptied_are_different_answers — passed, dispatched
  • tests/test_capture.py::test_an_overgrown_series_is_compacted_and_still_replays — passed, dispatched
  • tests/test_capture.py::test_eviction_drops_the_least_recently_retrieved_and_leaves_a_tombstone — passed, dispatched
  • tests/test_capture.py::test_a_push_hands_over_only_what_the_holder_has_not_been_given[server0] — passed, ungrounded
  • tests/test_capture.py::test_the_operator_can_push_a_series_and_an_outage_is_not_a_failed_command — passed, grounded
  • tests/test_capture.py::test_an_unreachable_holder_leaves_the_backlog_and_never_fails_the_run — passed, ungrounded
  • tests/test_capture.py::test_a_refusal_leaves_the_mark_where_it_was — passed, ungrounded
  • tests/test_capture.py::test_an_enrolment_naming_no_store_is_answered_rather_than_guessed_at — passed, ungrounded
  • tests/test_capture.py::test_a_backlog_larger_than_one_request_still_arrives_whole — passed, grounded
  • tests/test_capture.py::test_an_outage_partway_through_keeps_the_batches_that_landed — passed, ungrounded
  • tests/test_capture.py::test_one_record_over_budget_is_handed_over_alone_rather_than_dropped — passed, ungrounded
  • tests/test_capture.py::test_the_producer_batches_under_what_the_receiver_says_it_accepts — passed, dispatched
  • tests/test_capture.py::test_a_tombstone_is_not_evicted_again_and_does_not_cost_a_live_subject — passed, ungrounded
  • tests/test_end_to_end.py::test_a_series_accumulates_across_runs_and_is_never_written_unasked — passed, grounded
  • tests/test_series.py::test_a_series_records_what_changed_and_nothing_when_nothing_did — passed, ungrounded
  • tests/test_series.py::test_a_measurement_time_is_not_part_of_what_a_fact_says — passed, ungrounded
  • tests/test_series.py::test_a_fact_that_disappears_is_recorded_as_gone — passed, ungrounded
  • tests/test_series.py::test_the_history_replays_exactly — passed, ungrounded
  • tests/test_series.py::test_every_record_carries_a_unique_monotonic_sequence — passed, ungrounded
  • tests/test_series.py::test_compaction_says_what_it_dropped_and_still_replays — passed, ungrounded
  • tests/test_series.py::test_a_series_path_whose_directory_does_not_exist_yet_is_created — passed, ungrounded
  • tests/test_series.py::test_the_subject_comes_from_the_project_that_owns_the_series — passed, ungrounded
  • tests/test_series.py::test_a_series_belonging_to_no_project_is_refused_rather_than_guessed — passed, ungrounded
  • tests/test_series.py::test_the_project_asked_for_outranks_the_one_that_owns_the_file — passed, ungrounded
  • tests/test_series.py::test_the_command_pushes_under_the_subject_of_the_project_it_was_given — passed, grounded
Requirements (11)
What the user needs
  • dev07-6-2-ur1the mark moves only on acceptance, and only ever forwards
  • dev07-6-2-ur2what is outstanding, when too large for one request, splits into ordered batches; a failed batch stops the rest, and an outage partway keeps the batches that landed
  • dev07-6-2-ur3the hand-over itself — what is outstanding, retrying, acknowledgement and its outcomes — is dev07-6-2-1 · send what a run produced's
  • dev07-6-2-ur4what would be sent can be printed with nothing sent
  • dev07-6-2-ur6a discarded range comes back as discarded and never as a gap, and it is the first thing a reader is told
  • dev07-6-2-ur7the name a history is filed under is read from the project asked for, or from the project that owns the history, and never from where it was asked; finding no owner, the hand-over refuses rather than guessing — a correctly delivered history must not land under somebody else's name
What the system does
  • dev07-6-2-sr1what is sent and answered is the whole promise: how a holder lays out and stores a history is its own, promised to nobody, and an adopter reads the same answers from any holder
  • dev07-6-2-sr2a batch is sized to stay under the limit the holder publishes, with room to spare, because the two ends version separately and will drift
  • dev07-6-2-sr3what is outstanding is derived by comparing the mark to the history, never kept in a queue beside it — a queue beside a history is a copy free to disagree with it
How well
  • dev07-6-2-nfr1custodial, never telemetry: the adopter is the primary consumer, and what is held is held for them
Still open
  • dev07-6-2-u1one set of behaviours is owed by every way a holder may store a history, and who checks each of them against it is unsettled

dev07-6-2-1 send what a run produced Nothing holds it

As a developer I want the history handed to the holder I chose, so that it is held there and what did not arrive is still here.

Requirements (0)

dev07-6-2-2 hold a series Nothing holds it

As an IT professional I want the team's histories held on a box we already run, so that a history outgrowing the machine that wrote it is kept rather than lost.

Requirements (0)

dev07-6-3 read it back Proven

As a developer holding a board I want the history to answer when — when it changed, when we last looked, and what keeps changing — so that today is readable against every day before it.

The tests that cite it (18)
  • tests/test_capture.py::test_the_operator_can_read_a_history_back — passed, grounded
  • tests/test_capture.py::test_a_discarded_range_is_the_first_thing_a_reader_is_told — passed, grounded
  • tests/test_capture.py::test_a_history_can_be_fetched_from_the_holder_that_keeps_it — passed, grounded
  • tests/test_capture.py::test_pulling_what_the_holder_does_not_have_says_so — passed, grounded
  • tests/test_capture.py::test_a_pull_finds_its_holder_the_way_a_push_does — passed, grounded
  • tests/test_capture.py::test_a_fetched_copy_does_not_hand_its_note_to_the_next_holder — passed, grounded
  • tests/test_capture.py::test_a_pull_under_an_unreadable_configuration_says_so — passed, grounded
  • tests/test_series.py::test_when_we_last_looked_is_derived_and_never_invented — passed, ungrounded
  • tests/test_series.py::test_unchanged_is_not_unexamined — passed, ungrounded
  • tests/test_series.py::test_what_keeps_changing_is_counted_in_runs_and_never_in_records — passed, ungrounded
  • tests/test_series.py::test_one_subject_reads_back_as_when_it_broke — passed, ungrounded
  • tests/test_series.py::test_a_history_reports_and_never_grades — passed, ungrounded
  • tests/test_series.py::test_a_copy_a_holder_has_accepted_from_is_a_cache — passed, ungrounded
  • tests/test_series.py::test_a_pulled_copy_says_what_it_is_and_where_it_came_from — passed, ungrounded
  • tests/test_series.py::test_a_cache_may_be_longer_than_the_authority — passed, ungrounded
  • tests/test_series.py::test_show_tells_the_reader_which_copy_they_are_holding — passed, grounded
  • tests/test_series.py::test_a_pulled_copy_names_the_holder_it_came_from — passed, grounded
  • tests/test_series.py::test_a_pull_with_no_subject_says_where_it_looked_and_how_to_name_one — passed, grounded
Requirements (7)
What the user needs
  • dev07-6-3-ur1the read answers when a fact changed, when anybody last looked, and which subjects keep changing
  • dev07-6-3-ur2every copy says whether it is the history or a cache, so a copy is never read as a second opinion; a copy a holder has accepted from is a cache, and a cache may run longer than the history it was copied from
  • dev07-6-3-ur3no store answers a question about a range it does not hold as though it held it — the extent is stated on every read
  • dev07-6-3-ur4a copy fetched from a holder says what it is and names the holder
  • dev07-6-3-ur5the note that a copy was fetched belongs to that copy and is never handed over with it, so a holder never reads as a cache of another
What the system does
  • dev07-6-3-sr1handing over, reading and fetching a history are the same three asks wherever it is held, and give the same answers
  • dev07-6-3-sr2fetching a history finds its holder the way handing it over does, so it is read back from where it was sent

← Every chapter