Kernel: what a person placed, only a person ends

Merged
DO
1mo ago
+1855-359

Part of the epic "Epic: nine gaps in the Kernel, found in review". Closes #61.

The pull request's facts said whether a label was present and whether a thread was resolved, but not who did it, and had no kind for an App or the machine user. The reviewer's App could remove factory:hold and resolve the Maintainer's threads, and GitHub cannot narrow that. This follows the working ruling on #61, which gathers what the security passes on #33, #34, #55 and #60 left here.

The rule

ActBinds only when
Removing factory:holda person removed it; a Hold anyone else removed still binds
Placing factory:hands-offa person placed it; placed by anyone else it is read as a Hold (human_hold, evidence factory:hands-off), so it stops and takes a queued item out
Placing factory:admita person placed it, after the latest push; otherwise outside_not_admitted
Resolving a person's threadthat person resolved it
Resolving a Lens's threadthat Lens's App, or a person with write access, resolved it
Ending a request for changesa person did
Approvingthe machine user named as the approver, with write access
  • Every actor has a kind: human, lens, app or machine_user. A person is human with can_write exactly true. The port gives the kind from GitHub's account type and the configuration, never from a name's spelling (I-28, L-57). The one place a spelling is read only refuses: a human whose login ends in [bot], which GitHub user logins cannot contain, is unreadable. The approver read as any kind but machine_user, another name read as machine_user, or an agent's or dependency update's author read as anything but app, is unreadable too.
  • lens is a fourth kind beyond the ruling's three. A Lens's thread is closed only by that Lens's own App or a person, and telling the reviewer's App resolving its own Finding from the author agent's App resolving the threads that hold it needs a kind for an App that reports as a Lens. The port gives lens from the configuration's Lens Apps.
  • Labels are events. label_events (who placed or removed which label, when) replaces labels and admitted_at. What a person placed binds until a person removes it, and nobody else placing it again replaces the person's placement. In the same second a removal is read first, so the label stands. complete.timeline covers the events, and hands-off binds only when they were read in full: a timeline read short, which GitHub pages oldest first, could otherwise drop a person's later removal and keep a queued item in the queue.
  • An actor or label event that cannot be read defers for the Maintainer (label_unreadable, thread_unreadable, review_unreadable), and a queued item leaves the queue (#33).
  • The guard #34 added by name is replaced by the kind rule.

Tests

The OnlyAPersonEnds class in tests/test_decide.py holds a boundary test for each rule, written first, and each has a mutant: 203 of 203 killed. Counter-examples for an actor without its kind, a kind the Kernel does not know, a label event without who made it, and a thread resolved by a name alone. In the simulator an App takes a Hold off, adds hands-off and resolves the Maintainer's thread, and a held item never moves on except to be dequeued (test_what_an_app_does_in_a_persons_place_ends_nothing).

Documents: design §3.3, §4.7 (the Hold, Release, Hands-off and Admit rows), I-21 and I-28; L-17 and L-02; Boundaries rows in decisions 0003, 0005 and 0007 (no Decision or Why text changed); docs/standards/code.md, docs/standards/security-boundaries.md, tests/AGENTS.md. config/apps.json and its schema read the timeline in place of the labels.

Read by

A fresh-context review and a separate security pass (Claude), on the first commit; the second commit answers them. The security pass found no way for an App, the author agent, the machine user or a non-writer to release a Hold, admit an item, close a gate or approve; 46,268 random schema-valid facts never made the Kernel raise. Both found that a timeline read short could keep a removed hands-off binding and block a dequeue, now fixed. make verify passes on a git archive export (367 tests).

🤖 Generated with Claude Code

Summary by CodeRabbit

  • New Features

    • Pull-request decisions now account for who placed or removed control labels, who resolved review threads, and whether a person has write access.
    • Label history and actor details are included in pull-request facts, enabling decisions to reflect event order and actor identity.
    • Unreadable or incomplete timeline and actor information can defer an item for review and remove it from the merge queue.
    • Outside items require a person’s admission after the author’s latest push.
  • Documentation

    • Updated architecture, security, and decision guidance to describe the revised review, label, and actor rules.