Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
# 0215. No Role is named to open pull requests until open_pull_request has its writer

Status: accepted. The ruling of 2026-11-13 on box 13 of "Epic: slice 1, first approval. A Release on next reviews a pull request to this repo, and the machine user's approval stands" (issue 182), by the Solution Architect, delegated, with the Factory Builder, on the Maintainer's approval while away; built for "A check refuses naming a Role to open pull requests while open_pull_request has no writer" (issue 808), which restates the limit of "Acceptance: a pull request is bound to the issue it serves by its Run or branch, not by its author's closing link" (issue 295), its design ruled by the Factory Builder on 2026-11-13. It amends decision 0068's row "The Run record" and decision 0047's row "The known limit".

## Decision

| What | Decided | Because |
|---|---|---|
| The limit, restated | The gap a pull request's author's closing link leaves, which "Acceptance: a pull request is bound to the issue it serves by its Run or branch, not by its author's closing link" (issue 295) said must not outlive slice 1, must not outlive the moment any Role is named to open pull requests, or any contract is in force | The binding by the opening Run's record and by its branch is built and tested; its writer, "Acceptance: a pull request the Factory opens is bound to its issue by the Run that opened it" (issue 342), waits on the push Effect, which is slice 2's. Nothing the binding guards exists yet: no Role opens a pull request, and no contract is in force |
| The check | `tools/check_authority.py` refuses a configuration that names a Role for `open-pull-request` in `issues.intents` while `open_pull_request` has no writer, and names the first part of the writer missing. With the Role null, as `config/defaults.json` has it, it passes. `tools/check_examples.py` holds a configuration's counter-example to it | A limit that is only remembered is not held |
| The writer | Three marks, each read from the code's syntax, never by importing it: an adapter function under `adapters/` that builds a request whose method is `POST`, the one write that creates, and whose path is a repo's pulls and nothing after it, each read as text: a literal, one formatted with `%`, an f-string, or a name bound once to one of those in the function or at its module's top, given by place or by keyword; a step of the Harness that `tools/check_writes.py`'s CALLERS lists as reaching that function; and, in that step's module, a call of `harness/apply.py`'s `opened`, imported absolutely or relatively, or spelt out where `import harness.apply` binds it, which records the Run that opened the pull request (decision 0097) | The writer the row above waits on is the change that makes all three true. A read of the pulls, another write to them, a write to one pull request, a caller outside the Harness, and a step that records nothing do not. A method or a path that cannot be read as text is not read as an opening, so it never turns the check green; a writer written that way stays red, and the refusal says which mark it lacks |
| What remains | Nothing checks that no contract is in force: the check holds the Role half of the restated limit alone. The marks are syntax: a step could call `opened` and reach the opening adapter without opening a pull request in the same flow. CALLERS is held true by `tools/check_writes.py`, never by this check | Named, for the change that brings in the first contract |

## Why

Naming an opening Role in `config/defaults.json` is a one-line change, and the Kernel would then bind that Role's pull requests by their branch and their opening Run's record, while no Run ever records one. A check makes the configuration and the writer land together.

## Boundaries

| Boundary | Check |
|---|---|
| A Role named for `open-pull-request` is refused until an adapter opens a pull request, a step of the Harness reaches it as CALLERS lists, and that step calls `opened`, each missing part named in turn; a read of the pulls, a write to them other than `POST`, a write to one pull request, a method or a path not written as text, a caller outside the Harness, a step reaching another writer, and a step calling no `opened`, another module's, or `harness.apply.opened` spelt out with `harness.apply` not imported do not count; a path held in a name bound once, a module's constant, a keyword and an f-string are read, a name bound twice and a pull request's own path are not; `opened` imported by its name, under another, relatively, or with `harness.apply` whole, does, and by its own name in `harness/apply.py` alone; none named passes; the counter-example is refused | `tests/test_tools.py::test_a_role_named_to_open_pull_requests_waits_on_its_writer`, `tools/check_authority.py`, `tools/check_examples.py`, mutant: "a Role named to open pull requests is never refused", mutant: "an opening Role named none is refused", mutant: "a read of a repo's pulls opens one", mutant: "a method not written as text may open one", mutant: "a write to one pull request opens one", mutant: "any request opens a pull request", mutant: "a caller outside the Harness reaches the opening", mutant: "a step reaching any writer reaches the opening", mutant: "a step need not record the opening", mutant: "any write to a repo's pulls opens one", mutant: "opened imported by its own name records nothing", mutant: "harness.apply.opened spelt out records the opening with nothing imported", mutant: "harness.apply imported whole records nothing", mutant: "a path held in a name is not read", mutant: "a name bound twice is read by its first", mutant: "a module's constant is not read", mutant: "an argument by keyword is not read", mutant: "an f-string is not read", mutant: "a relative import of the Harness records nothing", mutant: "opened by its own name records the opening anywhere", mutant: "opened by its own name records nothing in harness/apply.py", mutant: "any module's opened records the opening", mutant: "any call of a step's records the opening", mutant: "opened imported under another name records nothing", mutant: "harness.apply imported under another name records nothing", mutant: "the configuration is not held to the opening", mutant: "a counter-example configuration is not held to the opening", `examples/invalid/config.an-opening-role-with-no-writer.json` |
92 changes: 92 additions & 0 deletions examples/invalid/config.an-opening-role-with-no-writer.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,92 @@
{
"schema": "config/1",
"approver": "donpetry-bot",
"author_role": null,
"owner_role": "pr-review",
"required_lenses": {
"deterministic": [
{
"lens": "verify",
"check": "verify",
"app_id": 15368,
"workflow": ".github/workflows/verify.yml"
},
{
"lens": "secret-scan",
"check": "Secret scan (gitleaks)",
"app_id": 15368,
"workflow": ".github/workflows/ci.yml"
},
{
"lens": "code-scanning",
"check": "CodeQL",
"app_id": 57789,
"workflow": null
}
],
"model": [
"pr-review"
],
"model_not_required_for": [
"dependency"
]
},
"status_on_item": "factory",
"check_conclusions": {
"success": "passing",
"failure": "failing",
"timed_out": "failing",
"queued": "pending",
"in_progress": "pending",
"pending": "pending",
"waiting": "pending",
"requested": "pending",
"expected": "pending",
"neutral": "unreadable",
"skipped": "unreadable",
"cancelled": "unreadable",
"stale": "unreadable",
"action_required": "unreadable",
"startup_failure": "unreadable",
"error": "unreadable"
},
"acceptance_reporters": {
"test": "verify",
"scenario": null,
"mutation": null,
"static": null,
"role": null
},
"limits": {
"max_attempts": 3,
"max_rounds": 3,
"max_runs_per_item": 10,
"max_environment_runs_per_item": 30,
"max_unmerged_closes": 1,
"org_max_active_runs": 4,
"max_diff_lines": 4000,
"max_diff_characters": 60000,
"max_acts_per_item": 6,
"max_path_length": 255,
"max_close_lag_seconds": 300,
"max_unnamed_run_seconds": 60,
"max_unnamed_runs": 1
},
"issues": {
"served_from": null,
"left_out_labels": [],
"left_out_types": [],
"label_apps": {
"factory:triage": null,
"factory:ready": null
},
"intents": {
"investigate-issue": null,
"judge-readiness": null,
"open-pull-request": {
"role": "dev-lead",
"app": "combsmith-sf-dev-lead"
}
}
}
}
84 changes: 84 additions & 0 deletions tests/test_tools.py
Original file line number Diff line number Diff line change
Expand Up @@ -919,6 +919,90 @@ def test_a_role_the_configuration_names_has_a_manifest(self): # issue 675
(field, name))
self.assertTrue(caught(check_authority.run(config=dict(config, owner_role=None)), "no Role's name"))

def test_a_role_named_to_open_pull_requests_waits_on_its_writer(self): # issue 808
# No Role is named to open pull requests until open_pull_request has its writer, issue 342's: an adapter that
# sends a write to a repo's pulls, a step of the Harness that CALLERS lists as reaching it, and, in that step, a
# call of harness/apply.py's opened. The refusal names the first missing; with none named, as in slice 1, it passes.
config = json.loads((ROOT / "config" / "defaults.json").read_text())
self.assertIsNone(config["issues"]["intents"]["open-pull-request"])
self.assertEqual(check_authority.opening_problems(config), [])
named = copy.deepcopy(config)
named["issues"]["intents"]["open-pull-request"] = {"role": "dev-lead", "app": "combsmith-sf-dev-lead"}
self.assertTrue(caught(check_authority.run(config=named), "no adapter sends a write to a repo's pulls"))
# Its counter-example is refused, for that alone.
self.assertFalse(caught(check_examples.run(), "config.an-opening-role-with-no-writer.json"))
opener = "adapters.opening:open_pull_request"
step = "harness/open_step.py"

def tree(adapter, harness, at=step):
folder = tempfile.TemporaryDirectory()
self.addCleanup(folder.cleanup)
root = pathlib.Path(folder.name)
for part, text in (("adapters/opening.py", adapter), (at, harness)):
(root / part).parent.mkdir(exist_ok=True)
(root / part).write_text(text)
return root

opens = "def open_pull_request(transport, repo):\n return request('POST', '/repos/%s/pulls' % repo, body={})\n"
records = "from harness import apply\n\ndef run(t):\n return apply.opened('e1', 1, 'b', None)\n"
callers = {step: {opener}}
self.assertEqual(check_authority.opening_problems(named, tree(opens, records), callers), [])
# The path held in a name bound once in the function or at the module's top, given by keyword, or written as an
# f-string, is read; a name bound twice, and an f-string with a pull request's number after it, are not.
for adapter in ("def open_pull_request(transport, repo):\n pulls = '/repos/%s/pulls' % repo\n"
" request('GET', pulls + '?head=x')\n return request('POST', pulls, body={})\n",
"PULLS = '/repos/%s/pulls'\n\ndef open_pull_request(transport, repo):\n return request('POST', PULLS % repo)\n",
"def open_pull_request(transport, repo):\n return request(method='POST', path='/repos/%s/pulls' % repo)\n",
"def open_pull_request(transport, repo):\n return request('POST', f'/repos/{repo}/pulls')\n"):
with self.subTest(adapter=adapter):
self.assertEqual(check_authority.opening_problems(named, tree(adapter, records), callers), [])
for adapter in ("def open_pull_request(transport, repo):\n pulls = '/repos/%s/pulls'\n pulls = '/repos/%s/issues'\n"
" return request('POST', pulls % repo)\n",
"def open_pull_request(transport, repo, n):\n return request('POST', f'/repos/{repo}/pulls/{n}')\n"):
with self.subTest(adapter=adapter):
self.assertTrue(caught(check_authority.opening_problems(named, tree(adapter, records), callers),
"no adapter sends a write"))
# Each part missing in turn is named. A read of the pulls, a write to one pull request, a method or a path not
# written as text, a call that builds no request, and a write to the pulls that creates nothing open none.
for adapter in ("def open_pull_request(transport, repo):\n return request('GET', '/repos/%s/pulls' % repo)\n",
"def open_pull_request(transport, repo):\n return request('PATCH', '/repos/%s/pulls/%d' % (repo, 1))\n",
"def open_pull_request(transport, repo, verb):\n return request(verb, '/repos/%s/pulls' % repo)\n",
"def open_pull_request(transport, path):\n return request('POST', path)\n",
"def open_pull_request(transport, repo):\n return send('POST', '/repos/%s/pulls' % repo)\n",
"def open_pull_request(transport, repo):\n return request('DELETE', '/repos/%s/pulls' % repo)\n"):
with self.subTest(adapter=adapter):
self.assertTrue(caught(check_authority.opening_problems(named, tree(adapter, records), callers),
"no adapter sends a write"))
# A caller outside the Harness, or a step that reaches another writer, does not reach the opening.
for listed in ({}, {"release/move.py": {opener}}, {step: {"adapters.effects:_review"}}):
with self.subTest(callers=listed):
self.assertTrue(caught(check_authority.opening_problems(named, tree(opens, records), listed),
"no step of the Harness reaches adapters.opening:open_pull_request"))
# A step that reaches the opening and calls no opened, or another module's, records no Run: harness.apply.opened
# spelt out, with harness.apply not imported, is another's.
for harness in ("def run(t):\n return None\n", "from harness import read\n\ndef run(t):\n return read.opened(1)\n",
"from harness import apply\n\ndef run(t):\n return apply.recorded(1)\n",
"def run(harness):\n return harness.apply.opened('e1', 1, 'b', None)\n",
"import json as harness\n\ndef run(t):\n return harness.apply.opened('e1', 1, 'b', None)\n"):
with self.subTest(harness=harness):
self.assertTrue(caught(check_authority.opening_problems(named, tree(opens, harness), callers),
"never call harness/apply.py's opened"))
# opened imported by its name, under another, or harness.apply imported whole, records it.
for harness in ("from harness.apply import opened\n\ndef run(t):\n return opened('e1', 1, 'b', None)\n",
"from harness.apply import opened as recorded\n\ndef run(t):\n return recorded('e1', 1, 'b', None)\n",
"import harness.apply\n\ndef run(t):\n return harness.apply.opened('e1', 1, 'b', None)\n",
"import harness.apply as a\n\ndef run(t):\n return a.opened('e1', 1, 'b', None)\n",
"from . import apply\n\ndef run(t):\n return apply.opened('e1', 1, 'b', None)\n",
"from .apply import opened\n\ndef run(t):\n return opened('e1', 1, 'b', None)\n"):
with self.subTest(harness=harness):
self.assertEqual(check_authority.opening_problems(named, tree(opens, harness), callers), [])
# opened by its own name records the opening in harness/apply.py alone; elsewhere, unimported, it is another's.
bare = "def run(t):\n return opened('e1', 1, 'b', None)\n"
self.assertEqual(check_authority.opening_problems(named, tree(opens, bare, "harness/apply.py"),
{"harness/apply.py": {opener}}), [])
self.assertTrue(caught(check_authority.opening_problems(named, tree(opens, bare), callers),
"never call harness/apply.py's opened"))

def test_a_value_held_twice_must_agree(self):
self.table["max_rounds"] = 9
self.assertTrue(caught(check_authority.run(self.table), "max_rounds differs"))
Expand Down
Loading
Loading