Skip to content

Checks: only the callers the check lists reach a GitHub write (#587) - #597

Merged
don-petry merged 19 commits into
mainfrom
checks/writes-allowlist
Nov 7, 2026
Merged

don-petry merged 19 commits into
mainfrom
checks/writes-allowlist

Conversation

@don-petry

@don-petry don-petry commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor

Closes #587. The decision record is 0153, numbered at enqueue after 0151 and 0152, with main merged in after the factory/v0.1.0 cut.

Important

Protected edit, for the Maintainer: AGENTS.md's table of rules changes in one row. Its row on the network now also names this check: "…; outside adapters/, only the callers a check lists reach a GitHub write | tools/check_repo.py, tools/check_writes.py". The row is folded into an existing one because the file's limit is 60 lines.

The check

tools/check_writes.py, run by make verify, reads the code by its syntax and never imports it.

A write is a request built by adapters/github.py's request with POST, PUT, PATCH or DELETE. Two are not writes:

  • a GraphQL POST whose document is a query with no mutation in it anywhere;
  • a token minted or revoked, which is a credential (%d holes only).

A writer is an adapter function that holds a write. A function reaches a writer when it does any of these, through any number of calls, modules and re-exports:

  • calls it, names it, or names a constant that holds it;
  • names a class one of whose methods, or whose bases' methods, reaches it;
  • reaches it through self, cls or super().

The callers. Outside adapters/ and tests/, exactly six modules reach a writer, each the writers CALLERS lists. The Factory Builder ruled for transitive callers, which adds harness/approve_step.py and harness/queue_step.py to the issue's four.

Caller Writers it reaches
harness/apply_step.py effects._review, _check, _comment
harness/approve.py, harness/approve_step.py effects.approve
harness/queue.py, harness/queue_step.py queue.enqueue, dequeue, resolve (the only GraphQL mutations)
release/move.py tags.write, deployments.record

What fails:

  • a new caller;
  • a caller that reaches a writer it does not list, or no longer reaches one it lists;
  • outside adapters/, any request that is not a read;
  • outside adapters/, a write verb held as a whole string, except in the two hooks that classify gh commands.

What the syntax cannot read is a problem, never a pass. The cases:

  • a method or a query that is not a literal;
  • a name a module does not define, or binds two ways;
  • import *;
  • a module that reaches a write handed on as a value;
  • a request built by hand, or changed after it is built;
  • an import of importlib or builtins (except in tools/mutants.py);
  • a test imported from outside tests/ (except in tools/make_corpus.py).

The check is clean on main, and on this branch merged with main at a32c0ce.

The record

Decision 0153 holds the rulings and names, one line each, what this check does not hold:

  • the Controller's writes, entered from pass.yml;
  • the workflows' dispatches;
  • the trial scripts' writes;
  • gh run from Python;
  • code written to hide a write.

The last uses the Builder's words: "a net for code written plainly; code written to hide a write is the review's to see". The routes still open that only such code would take are in #596.

Checks

  • At f6cf165 (record numbered in an export), make verify passed and all 77 mutants of tools/check_writes.py were killed.
  • The numbered record and main merged in, at e36113d, are run again before enqueue.

Reviews

Reader At Found Disposition
Claude 7f33201 4 majors: unresolved names; requests built by hand; a mutation after a query; speed Fixed in 5201952
Argon (9 parts) 7f33201 2 blocking and 9 major, mostly the same Fixed in 5201952 and 1f1b1b8
Muse 7f33201 2 blocking and 1 major, the same Fixed in 5201952
Claude 1f1b1b8 4 gaps: a name stored under an if; a constant filled later; a credential's %s; a request edited once built Fixed in 2fb1da0
Argon (8 parts) 1f1b1b8 4 blocking and 8 major: names bound two ways; loads by name; mutants too coarse Fixed in 5529e69 and d0f87dd
Muse 1f1b1b8 No read: the plan's usage limit was hit Owed (quota); Astra read in its place
Astra 5529e69 10 blocking: loads by name; re-export depth; shadowing; body keys; request edits Fixed in d0f87dd
Astra d0f87dd 8 blocking: rarer routes (builtins.__import__, __dict__, nested scopes, super() overrides, nested fills) Fixed in 4e5b288, the last round by the Builder's ruling. Later such routes go to #596
Astra, Codex e7ab41d to 899121b Plain-code cases: a parameter's default; += and aliased registries; a conditional rebind; a class attribute through cls; super() across modules; a local import into a parameter; a relative import * Fixed in 6e8fae5, 54a8517, da7d051 and 899121b. The evasions (global, a copied request, a nested body edit) went to #596
Astra 899121b Template-method cls dispatch; a nested function's import Fixed in 2ff8308. Its four evasions went to #596
Astra, the last read 2ff8308 A surviving += mutant; four routes through classes or registries The mutant fixed in 0d383c3. By the Builder's ruling, every route through classes, scopes or registries goes to #596
Codex 899121b The NNNN record name Declined: numbered at enqueue

🤖 Generated with Claude Code

don-petry and others added 9 commits November 6, 2026 19:36
tools/check_writes.py reads the code by its syntax and never imports it. A write is a request built
by adapters/github.py's request with POST, PUT, PATCH or DELETE. A GraphQL query sent by POST is not
one, and neither is a token minted or revoked. A writer is an adapter function that holds a write. A
function reaches one when it calls it, names it, or names a class one of whose methods reaches it,
through any number of calls.

Outside adapters/ and the tests, six callers reach a writer, each exactly the writers CALLERS lists:
- harness/apply_step.py
- harness/approve.py and harness/approve_step.py
- harness/queue.py and harness/queue_step.py
- release/move.py

A new caller fails, as does a caller that reaches a writer it does not list, or a listing no longer
true. Outside adapters/, a request must be a read, and no Python holds a write verb as a whole string
but the two hooks that read one. A method or a query the syntax cannot read, or an adapter module
used as a value, is a problem.

make verify runs it. Decision 0150 records it, with the Factory Builder's rulings:
- the callers are read transitively, which adds approve_step and queue_step;
- the issue's line on queue_step was wrong;
- the paths this check does not hold are named, each with what holds it.

AGENTS.md's row on the network names the check.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ails closed on what it cannot read

From the Claude review of #587. Each of these got past the check before:

1. A name the check could not resolve was skipped. That covered a dotted name
   (adapters.effects.role_write), a re-export from another module or an adapter, and a module constant
   that names a writer. Names now resolve through dotted chains, imports and re-exports, a module's
   constants are read as units of their own, and a name a module of the repo does not define is a
   problem.
2. An adapter could send a dict with a method that it built by hand, and the transport would rebuild
   it. A request built that way is now a problem outside adapters/github.py, and so is request named
   but not called.
3. A document holding a query and then a mutation read as a query, and so did a query a function sets
   itself over the module's. A mutation anywhere in the document is now a write. A name the function
   sets, or a body spread from a value, is a problem.
4. A module that reaches a write, handed on as a value, is a problem, as an adapter is. So is
   import * from the repo, and a module loaded by its name, except in tools/mutants.py.
5. Naming a class follows its bases and its own body, so a subclass reaches what its base does.

Each module is walked once, and each test plants all its cases in one copy of the repo, so the tests
take 15 seconds where they took 47. There are 28 mutants. The record names gh run from Python as not
held here, and its date is the day of the rulings.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…lled with text

Argon's and Muse's reads of #587 were of 7f33201, before the rewrite in 5201952, which covers what
they raised but for these:
- A module binds each name in one table, so a name both defined and imported, or imported twice under
  one name, was read one way. Which binding a function means cannot be told by the syntax, so a name
  bound two ways is now a problem.
- A query made by a % format was read by its left side, though the right may fill it with a mutation.
  A formatted query is read only where each hole takes a number, as adapters/items.py's does.
- The tests now hand a writer on uncalled, and have a listed caller reach only some of what it lists.

Four new mutants; 32 in all.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…and refuses a request edited once built

From the second Claude review of #587, which tried 43 ways round the check at 1f1b1b8 and found
four it let through:
- A name a module stores some other way than plainly, under an if, in a tuple or a loop, was read as
  nothing when another module imported it. It is now read as all its module's top level.
- A constant filled at the top level after it is made, such as STEPS['approve'] = effects.approve,
  held only what it was made with. What fills it is now part of it. An adapter's constant filled from
  a function, a decorator's registry, cannot be read, and is a problem.
- A credential's path with a hole for text could name another path. Only %d is now a credential.
- A request whose method, path or body is set after request built it is sent as set, and is now a
  problem outside adapters/github.py.

A test imported from outside tests/, which the check does not read, is a problem too, but in
tools/make_corpus.py. Seven new mutants; 39 in all.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…s are finer

From Argon's read of #587 at 1f1b1b8:
- A name defined twice, or both defined and assigned, is bound two ways, here or in the module it is
  imported from. A constant assigned twice holds what each assignment names.
- A module loaded by a literal name is refused when that module reaches a write, as an adapter is.
- The mutants were too coarse to show their tests. The listed-caller check, the module-as-value check,
  the load by name and the write outside adapters/ are each now broken one part at a time. Tests now
  hand on an adapter that writes nothing, the adapters package itself, a load by a variable, and a
  GraphQL document that is neither a query nor a mutation.

Fifty mutants in all.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…cls and super() into a base

From Astra's read of #587 at 5529e69, standing in for Muse, whose plan's limit was hit, and Argon's
part 6 at 1f1b1b8:
- A module loaded by a name could take any name: a renamed import_module, a formatted one, a relative
  one, or a test. An import of importlib, or __import__ named, is now a problem anywhere but
  tools/mutants.py.
- A re-export chain deeper than eight was dropped. It is now followed to any depth, and one that comes
  back to itself is a problem.
- A name stored under an if, used in its own module, was read as nothing. A query constant assigned
  again, to anything but that one text, was read as its first text. A parameter could shadow a query,
  and a body key that is no literal could replace one. Each now fails closed.
- A request changed after it is built, by a call on it such as update with pairs, is a problem.
- An adapter holding another as a value is a problem, as anywhere else.
- self, cls and super() reach a method of the class or of its bases.
- A function's own names now shadow the module's, as Python reads them, so effects.py's local threads
  is no module handed on.

59 mutants in all.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…thon does

From Astra's second read of #587, at d0f87dd:
- A query constant rebound under an if, or by an augmented assignment, is no constant.
- A constant filled two keys deep, such as TABLE['a']['b'] = w, holds what fills it.
- An adapter's namespace, __dict__ imported, is the module handed on.
- super() reaches the bases alone, so an override that calls the method of the same name above it is
  followed, not read as calling itself.
- A function's own names are those of its own scope. A nested function's parameter no longer hides
  the outer function's call to a writer.
- A query whose dotted root a parameter takes is refused.
- A request bound by an annotated assignment, or to another name after, is followed when changed.
- builtins, like importlib, is refused, so __import__ cannot be imported under another name.

68 mutants in all.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
On the Factory Builder's ruling on the reads of #587, the record names code written to hide a write as
the review's to see, in the words tools/check_repo.py uses of its net for the network. The routes
still open that only such code would take are issue 596's.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@don-petry
don-petry requested a review from a team as a code owner November 7, 2026 04:59
@coderabbitai

coderabbitai Bot commented Nov 7, 2026 •

Copy link
Copy Markdown

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

Run configuration

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • Trigger review
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 7, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-07T07:49:07.097699Z e36113d New commits
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

SonarCloud on #597: _lookup gave a module as a pair and all else as a triple. A module is now a triple
too, its third part empty.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e7ab41d18a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread tools/check_writes.py Resolved
Comment thread tools/check_writes.py Resolved
Comment thread tools/check_writes.py Resolved
Comment thread tools/check_writes.py Resolved
… into a parameter, and a relative import *

Astra's read of #587's last head found three cases on code written plainly:
- super() skipped a base class of the same name in another module, such as Client(BaseClient). A
  class's own methods are now those of its own module and name.
- A parameter that a local import fills when no value is given was read as a parameter, so the writer
  the import names was lost. A name a function imports in its own scope is the import's.
- A relative import * was looked for under its bare name. It is now read where it comes from.

Its two other finds, a query constant set again through global and a request's body edited a key
deep, are routes only code written to hide a write would take, and go to issue 596. 71 mutants.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
don-petry and others added 2 commits November 6, 2026 23:09
…ned, and a registry filled by +=

Codex on #597, two cases on code written plainly:
- A parameter whose default is an imported writer, def go(t, approve=approve), skipped both the
  default and the calls, since approve was a parameter. A default is now read in the scope the
  function is defined in.
- A registry filled by STEPS += [approve] held nothing of it. An augmented assignment now fills the
  constant it names.

Its relative import * was fixed in 6e8fae5. Its request body edited a key deep is a route only code
written to hide a write would take, and is issue 596's. 73 mutants.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…class attribute called through cls

Astra's read of #597 at 6e8fae5, two cases on code written plainly:
- A constant set plainly, then rebound to a writer under an if, ACTION = None then if ...: ACTION =
  role_write, kept only its first value. A top-level statement that stores into a constant, under an
  if or a try too, is now part of it.
- A class attribute holding a writer, write = staticmethod(role_write), called through cls.write,
  was no method and was dropped. An attribute self or cls takes that the class's body, or a base's,
  assigns is now that body.

Its default parameter was fixed in 54a8517. A query set again through global, and a request copied
and then changed, are routes only code written to hide a write would take, and are issue 596's.
75 mutants.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: da7d051b6b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread tools/check_writes.py Resolved
… for it

Codex on #597 at da7d051: STEPS = [] then registry = STEPS and registry.append(approve) filled only
registry's unit, so a caller of STEPS reached nothing. A constant that is another constant is now the
one container: what fills either fills both. 76 mutants.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 899121b1e9

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

don-petry and others added 5 commits November 6, 2026 23:29
…ide, and a nested function's import

Astra's read of #597 at 899121b, two cases on code written plainly:
- A base's method calling cls.write(), which a subclass overrides, reached only the base's write;
  Python runs the subclass's. self.m and cls.m now reach m in each subclass as well.
- A writer a nested function imports under the name an outer parameter has was read as that
  parameter. A name imported anywhere in a function, a nested function's import too, is the import's.

Its other four finds are routes only code written to hide a write would take and are issue 596's:
- a query rebound through global;
- a request copied, then changed;
- a request's body edited a key deep;
- a registry a decorator fills through a local name for it.

78 mutants.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… into a constant

Astra's last read of #597, at 2ff8308: the mutant that dropped the += branch of _filled_names
survived. A top-level STEPS += [w] is already a store into STEPS, which the rule for a constant
rebound under an if joins to it. The branch and its mutant are taken out, and that rule's mutant holds
the += case. 77 mutants.

Its four other finds go to issue 596, by the Factory Builder's ruling that every route through
classes, scopes or registries is that issue's:
- super() through a sibling base;
- a subclass's callback attribute;
- a request copied, then changed;
- a decorator's registry given as a parameter's default.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… so its mutant is killed

The mutant that makes a nested function's names the outer function's survived. A nested function's
parameters were never counted as the outer's, so only a name a nested function assigns tells the
rule, and the test now has one.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…1.0 cut

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The Factory Builder gave the number at enqueue, after 0151 and 0152, which are on main now.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@sonarqubecloud

sonarqubecloud Bot commented Nov 7, 2026

Copy link
Copy Markdown

@don-petry
don-petry added this pull request to the merge queue Nov 7, 2026
Merged via the queue into main with commit 4f5b141 Nov 7, 2026
23 checks passed
@don-petry
don-petry deleted the checks/writes-allowlist branch November 7, 2026 08:32
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.

Only the write steps call a write: a check that keeps GitHub writes to an allowlist of callers

1 participant