Skip to content

Records the after_step: driver seam as a proposed ADR-0008 amendment - #89

Merged
johnnyt merged 1 commit into
mainfrom
sp-sli-adr-0008-after-step
Sep 8, 2026
Merged

Records the after_step: driver seam as a proposed ADR-0008 amendment#89
johnnyt merged 1 commit into
mainfrom
sp-sli-adr-0008-after-step

Conversation

@johnnyt

@johnnyt johnnyt commented Sep 8, 2026

Copy link
Copy Markdown
Member

Bead sp-sli (campaign-SF039 lane P, plan key pr1). Records the
after_step: driver seam as a proposed amendment at the end of
docs/adr/0008-durable-subchart-child-runs.md, per the operator's
campaign-SF039 ruling RQ-SF039-13.

What the amendment says

  • S1 Driver.new/3 takes after_step:, a 3-arity
    (run_id, machine_state, effects) function, stored on the struct and
    nil by default. The third argument is the step's whole effect list, as
    Runs' persist tail was handed it, not the executable subset the
    driver's own executor sees; the seam that carries it out of Runs is
    sp-c48's, with a widened public Runs return ruled out.
  • S2 It fires after every Runs entry point the driver calls -
    Runs.create/4 and the private step/5's Runs.step/5, reached from
    the answer loop and from both late-answer doors - with the id of the run
    that was stepped. That covers the parent's step on the answer path,
    including Runs.fail/4's driver: path, and it reaches nested drives
    for free because a child driver and a resolved parent driver are both
    built as %{driver | machine: ...}. Runs.cascade_cancel/3 steps
    nothing and fires nothing.
  • S3 After the persist, in the order the steps happened, outside the
    exclusion of the run it reports. The section states the scope of that
    guarantee explicitly: decision 3's single child is created from inside
    the parent's step, so a child's callback can fire while the parent's
    exclusion is held; what is promised is that a run's callback never runs
    inside that run's own exclusion.
  • S4 The return is ignored; a raise propagates to the caller, and the
    cost (a part-taken drive, recovered by the same at-least-once re-drive
    as every other window in the record) is stated.
  • S5 Not a telemetry event - ADR-0009 stays untouched, and the two
    seams' opposite failure semantics are why both exist - and not a way to
    alter the step.

A worked example (the outside fail of a child answering its parent, the
host appending one row per parent step) and a "what this does not decide"
paragraph close the section.

Status

Proposed, with a status line so there is a line to flip. sp-c48
implements it; sp-nhl flips this section once that has landed. No lib/
change ships here - the same posture the sp-n8g amendment above records
for itself.

Provenance and checks

  • Appended at the END of the file, after the sp-y7n note it extends.
    git diff origin/main -- docs/adr/ is 188 insertions, 0 deletions.
  • Every code cite names a function-head anchor and the SHA it was read at
    (4e3e2c8); all were re-verified by anchor immediately before this
    request was opened.
  • Gate: not run, and none applies. The diff touches one Markdown file
    under docs/adr/ and no Elixir code, which is the CLAUDE.md authority
    table's "a change touching no Elixir code has no gate to run and may
    commit on review of the diff alone". CI runs the full gate on this
    branch regardless.
  • No changelog fragment: changelog.d/README.md lists documentation
    and ADRs on its "do not write a fragment" side.
  • Terminology firewall scan run over the outbound diff, bead text and this
    body, with a constructed positive control: clean, control fired.

Appends a dated amendment at the end of docs/adr/0008 stating the driver
callback a host needs to keep its own append-only run-events record in
step with what this package steps on its behalf: Driver.new/3 takes
after_step:, a 3-arity (run_id, machine_state, effects) function stored on
the struct and nil by default; it fires after every Runs entry point the
driver calls - the driven run's own steps and the parent's step on the
answer path alike, including Runs.fail/4's driver: path - with the id of
the run that was stepped; after the persist, in order, outside that run's
own exclusion; its return is ignored and a raise propagates; and it is
neither a telemetry event nor a way to alter the step.

Proposed, not accepted: no lib/ change ships with it. sp-c48 implements
the callback and sp-nhl flips the status line once that has landed - the
same posture the sp-n8g amendment records for itself.

Additive only: zero removed lines in docs/adr/, every decision and every
earlier note untouched, appended after the sp-y7n note it extends. Every
code cite in the new text names a function-head anchor and the SHA it was
read at (4e3e2c8).

Gate: not run, and no gate applies - the diff touches one Markdown file
under docs/adr/ and no Elixir code, which is the authority table's
"a change touching no Elixir code has no gate to run and may commit on
review of the diff alone". No changelog fragment: changelog.d/README.md
lists documentation and ADRs on its "do not write a fragment" side.

sp-sli
@johnnyt
johnnyt force-pushed the sp-sli-adr-0008-after-step branch from 16d982e to fd6a37e Compare September 8, 2026 21:56
@johnnyt

johnnyt commented Sep 8, 2026

Copy link
Copy Markdown
Member Author

Direction review pass 1 (head 16d982e): QUALIFIED, 1 finding, 0 blocking.

Finding (RECORD-PROSE, NON-BLOCKING): the new text credited the sp-y7n Note with describing campaign 031's fan-out proof working around the seam host-side; that sentence is in the sp-n8g amendment (docs/adr/0008 :447-449).

Cured in-branch at fd6a37e: the sentence now credits the sp-n8g amendment for the 031 description and the sp-y7n Note for answer_parent/3 being the explicit host door, plus one stray wrap the reviewer flagged as a tidy-up. Diff against origin/main is 189 insertions, 0 deletions. A fresh scope-frozen re-review follows.

@johnnyt

johnnyt commented Sep 8, 2026

Copy link
Copy Markdown
Member Author

Direction review pass 2 (scope-frozen re-review, head fd6a37e): UNQUALIFIED, 0 findings, 0 blocking, no new surface.

The pass-1 cure was verified from both sides and the misattribution is fixed rather than moved. Scope, append-at-end (189 insertions / 0 deletions), heading and status shape against the sp-n8g amendment, S1-S5 plus the worked example, no contradiction with ADR-0004 d6 / ADR-0008 d3 / ADR-0009 / ADR-0010, every code anchor present at the PR head with its 4e3e2c8 label, and the firewall scan clean with a control that fired.

Two non-qualifying advisories carry as residue rather than a cure (after UNQUALIFIED nothing is cured): this body's provenance section says 188 insertions where the cured diff is 189, and the section says "decision 5 below" where its other self-references say "clause N".

Merging under the campaign-SF039 grant: full gate not applicable (docs-only, per the CLAUDE.md authority table), CI green on fd6a37e, firewall clean with a constructed positive control, direction verdict UNQUALIFIED within budget.

@johnnyt
johnnyt merged commit 95ea54f into main Sep 8, 2026
1 check passed
@johnnyt
johnnyt deleted the sp-sli-adr-0008-after-step branch September 8, 2026 22:08
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