Skip to content

Simulator: issues, with the faults the reviews imagined #43

Closed

Description

@don-petry

Part of the epic "Epic: slice 0, foundations. The repo holds the line, its context is tested, and the platform facts are recorded".

Why. The simulator plays the poller, the Runs and the people, and breaks things on fixed seeds. For pull requests it found two errors in the design that no reading had. It has no issues in its world.

Done when

  • The world has issues: people who open, edit, label, comment, close and reopen them, with and without write access; the Controller's acts; and investigating, readiness and opening Runs.
  • Five faults are injected on fixed seeds: an outsider's edit after admission; a stranger's pull request naming an issue; a reopening by someone without write access; a label removed while a Run is in flight; run records that expire.
  • I-39 to I-44 are asserted after every step, and a failure prints its seed and a trace.
  • Every error it finds in the design is corrected in the design by pull request and recorded there, as §9.13 records the two found before.

Needs. The two Kernel stories before it. The rates at which people do these things are invented, as the pull request's are.

Design. §4.5, the simulator; §4.1, the issue Lifecycle; §4.4, I-39 to I-44; §9.13.

Activity

  1. don-petry commented on Oct 18, 2026

    @don-petry
    ContributorAuthor

    From #165, "Kernel: an issue goes stale as a pull request does", ruling 8: when the issue's world lands here, it checks an issue's staleness with the world's own count of when the issue last moved, as sim/world.py does a pull request's (I-1). Count from the sources kernel/issue.py's moved_at names:

    • the issue's life starting;
    • its content changing;
    • a writer acting or commenting;
    • a control label from a person or from the App declared for it;
    • a Run starting;
    • a linked pull request opening or closing.

    Use the limits per State in lifecycle/issue.json. Until then, #165's boundary tests hold it.

  2. don-petry commented on Oct 19, 2026

    @don-petry
    ContributorAuthor

    Dependency added (plan review, 2026-10-19)

    This story writes sim/world.py, sim/grounding.py and tests/test_simulator.py. So do #161 (ruling 7: the unnamed-run window on chosen seeds) and #163 (ruling 7: a_push_is_missing_from_the_activity). The lane rules listed only tools/mutants.py and test registration as shared between lanes; these three files join that list. This story starts after #163 merges, or rebases on each lane-a merge and re-verifies. Lane b builds #171 first.

    Also from the trial sitting for #14: the runbook expects the fake's an_approval_survives_a_push to be shown wrong under the canary's ruleset (an approval is dismissed as stale on push). That correction goes in the trial fixtures' PR, so build this story's issue world on the corrected rule.

  3. don-petry commented on Oct 20, 2026

    @don-petry
    ContributorAuthor

    Working rulings (overturnable in review)

    Solution Architect, delegated. On main at 31800f6 (#221). Read from the issue and its two comments (#165's ruling 8 on staleness; the plan review's shared-file dependency on #163, PR #223), design §4.1 (the issue Lifecycle), §4.4 (I-39 to I-44), §4.5, §9.13, the rulings on #41 and #42, kernel/issue.py as merged (decisions 0028, 0031, 0034, 0036, 0037), lifecycle/issue.json, sim/world.py, sim/grounding.py, tests/test_simulator.py, tests/test_transitions.py and trials/P-32.json.

    What this story decides. The simulator has one world, a pull request. This gives it a second, an issue, with the people, the Controller's acts and the three issue Runs the Lifecycle names, five faults on fixed seeds, and I-39 to I-44 checked after every step. It decides where that world lives, what it may draw on, which rules of the fake GitHub it adds and what grounds them, and what happens when it finds an error in the design.

    1. The issue world is a module of its own, sim/issues.py, beside sim/world.py and not inside it. IssueWorld(seed, faults=True, people=True) is one issue, as World is one pull request: a counter minute, a seeded generator drawn only through pick() and random(), note(), check() raising sim.world.Broken, check_unheld() and NOT_YET_HELD, each written as world.py writes it. It imports from sim.world only Broken, MAINTAINER, STRANGER, COLLEAGUE, START and at, and edits nothing there. It drives kernel.issue.decide and kernel.issue.still_admitted, and decides nothing itself. Why: sim/world.py is a protected path that lane a also writes (#163, ruling 7), and its seeds must keep replaying exactly (test_a_seed_replays_exactly); a second world inside it would change every draw. One item per world is what §4.5 built and §9.13 measured. sim/issues.py and its test join the protected paths in config/hooks.json, beside sim/world.py and tests/test_simulator.py: the simulator is one of the checks that hold the never-broken rules.

    2. The configuration the world gives the Kernel serves issues. config/defaults.json keeps every null the Maintainer left (0028, 0031): the world builds its own, as tests/test_issue.py's config() does, from the defaults with lifecycle/issue.json and an issues block that serves from START, leaves out the type Epic and the labels epic and idea, names the Controller's App for factory:triage and the readiness App for factory:ready, and maps the three Intents to business-analyst, readiness and dev-lead with their Apps. Why: what is turned on is the Maintainer's, in the data; what the world tests is the Kernel under a configuration that serves, which no data file holds yet.

    3. People, acts and Runs. On an even seed a person with write access opened the issue; on an odd seed an outsider did, and the Maintainer admits it on some seeds and not on others. By the seed alone, as world.py draws its class. Each step is one of: a pass (lost on some, as a_tick_can_be_lost); a Run starting or ending; the platform; a person.

    • A person with write access edits the content (a new content_id and content_changed_at), comments, adds or removes factory:hold, factory:hands-off, factory:admit, factory:triage or factory:ready, closes, reopens, marks the linked pull request ready or converts it back to draft, merges it with a non-empty or an empty diff, or closes it unmerged. Each act takes its own minute (I-6). An outsider edits, comments, reopens, or opens a pull request that names the issue.
    • The Controller's acts are the Kernel's Decisions applied: accept, remove_label, place_hold, each counted as an act (I-8), through the world's apply_action, as the pull request's enqueue and dequeue are.
    • A Run is admitted by the Kernel, listed queued, starts, and ends: investigate-issue leaves the investigating App's comment in role_comments; judge-readiness leaves factory:ready added by the readiness App, through an apply that asks the Kernel again with its own Run left out (I-38, still_admitted), or leaves nothing, as a shadow does; open-pull-request opens the Factory's draft with its branch_head. A Run can be killed at any step boundary, ending failure with outcome item, and now and then environment (§3.10). Attempts, rounds and the Run ceiling are the brakes' (0003); the world counts nothing itself.
    • The Pause, the model's deferral and the org's concurrency are drawn as world.py draws them, by the seed alone, so that every act and Run is held back on some seeds (0003).

    4. The five faults, each on seeds chosen by a constant, as UNNAMED_EVERY chooses. Every other seed stays as it was.

    1. An outsider's edit after admission: the admission stops counting; the next pass reads new, acceptance_lapsed, which needs a person, and no Run is admitted until the Maintainer admits again (I-42, 0037).
    2. A stranger's pull request naming the issue: it is in linked with class outside and no admission; it moves nothing (I-39), and the issue's State with it is the State without it.
    3. A reopening by someone without write access: reopened_last_by is other; the issue stays declined whatever labels it carries (row 2), until a person with write access reopens it, which begins a new life (I-41).
    4. A label removed while a Run is in flight: the Run's apply asks the Kernel again and writes nothing (I-38); factory:ready the readiness Run would have added is not added, and the issue stays in triage or goes where the facts say.
    5. Run records that expire: records older than the retention vanish from what the pass reads; the investigating App's comment, and the readiness App's label or comment, stand in for them (0031), and a Factory factory:ready whose Run record has expired does not count (0028). The retention is a constant of the world, short enough that the first 40 seeds reach it.

    Why by constants: the pull-request world's faults are drawn so; a fault that every seed meets at random cannot be told from a world that never reaches it, and tests/test_simulator.py holds each by the seeds that reach it.

    5. What is checked after every step. I-39 to I-44, each in the world's own words:

    • I-39: the Kernel's State with the stranger's pull request is the State without it, unless the Maintainer admitted it.
    • I-40: factory:ready is added by nobody but the readiness Run's apply, after a Result that covered the rubric, for the content it was admitted for; and neither factory:triage nor factory:ready is added again, for the same content, after a person removed it.
    • I-41: a label the Kernel counts was added by a person with write access or by its declared App; a Hold ends only when a person with write access removes it; a new life begins only when such a person reopens.
    • I-42: every Run the Kernel admits is on an accepted issue, and an investigating Run only when the content changed, a person with write access acted since the last, or the last ended without investigating and the attempts are not spent.
    • I-43: after an unmerged close, at most max_unmerged_closes further linked pull requests open before a person with write access acts.
    • I-44: the State is one of the declared, and never two Runs are in flight on the issue.
      Also I-1 by the world's own count, from the sources Kernel: an issue goes stale as a pull request does #165's ruling 8 names, against lifecycle/issue.json; I-8 (the act ceiling, the attempts, the Run ceiling); and I-12: every change of State the world makes, with who made it, is one tests/test_transitions.py's exploration of the issue finds, through check_lifecycle.undeclared and the issue Lifecycle, as the pull-request world holds it.

    6. The fake GitHub's new rules, appended to RULES in sim/grounding.py, each marked # GitHub: <code> where the world applies it:

    • an_issues_author_has_an_association: the listing says whether the author has write access (P-32, trials/P-32.json).
    • a_label_event_names_its_actor already exists, asking P-32, with no fixture: it is grounded now by trials/P-32.json, which this story is the first to apply to an issue.
    • a_closing_reference_is_read_from_any_pull_request: the issue a pull request closes, and its opener, are read from a draft, an open, a merged and a closed-unmerged pull request alike (P-33, unverified until Trials P-33 and P-34: the closing reference and an issue's content time are readable #184).
    • who_changed_the_draft_flag_is_read (P-33, unverified).
    • an_issues_content_time_is_read_apart: when the title or body last changed, apart from when anything did (P-34, unverified).
    • a_reopening_names_its_actor (P-34, unverified).
    • an_issues_run_record_expires: a run record is gone after the retention (P-16, unverified).
      Why: a rule no trial asks cannot be grounded; Trials P-33 and P-34: the closing reference and an issue's content time are readable #184 runs P-33 and P-34 and sets their fixtures. The world is built on these as the design states them, and the Maintainer sees each as unverified in make verify until then.

    7. Tests, written first, in tests/test_issue_simulator.py, added to SLOW in tools/verify.py beside test_simulator:

    • test_invariants_hold_under_faults: every seed of SIM_SEEDS, 250 steps, every check above; the changes of State made are among those the exploration finds; the seeds serve a writer's issue and an outsider's, admitted and not.
    • test_a_seed_replays_exactly.
    • test_the_seeds_reach_each_fault: each of the five, by its constant, on the first 40 seeds, with the Decision each produces.
    • test_a_stale_wait_shows_by_the_worlds_own_count (I-1, Kernel: an issue goes stale as a pull request does #165's ruling 8).
    • test_a_quiet_world_ends_at_rest: faults and people off, the issue ends done, declined, held, or new with acceptance_lapsed or not_accepted, within its steps.
    • test_every_change_of_state_is_checked_with_who_made_it (I-12).
    • test_a_broken_invariant_names_its_seed: a world made to break one, through a Roll, raises Broken naming the seed and the invariant.
      No new mutant: the simulator breaks nothing on purpose, and the Kernel rules it exercises each have theirs. A mutant is added only with a Kernel fix this story makes.

    8. If the world finds an error in the design, the fix goes in kernel/issue.py with a boundary case in tests/test_issue.py and its mutant, as sim/AGENTS.md says, and the design records it where §9.13 records the two found before, in a new paragraph of §4.5 or §9.13 naming the seed. That is this story's fourth box. The ruling names none in advance.

    9. Record. No new decision: the world checks what 0028, 0031, 0034, 0036 and 0037 decided. Rows, each naming its test: 0028 ("the world's seeds reach a stranger's pull request, a reopening by another and an expired record, and the State is as the rows say"), 0031 ("the world's Runs are admitted on accepted issues only, one at a time, and apply refuses after a label is removed in flight"), 0034 ("a wait shows stale by the world's own count"), 0003 ("a Run and an act are held back under a Pause on an issue's seeds"). Design: §4.5 gains the issue world in its World and Faults bullets and the sentence "I-39 to I-44 are checked after every step"; sim/AGENTS.md and tests/AGENTS.md name the module.

    10. Files, and shared files. New: sim/issues.py, tests/test_issue_simulator.py. Edited: sim/grounding.py (append), sim/AGENTS.md, tests/AGENTS.md, tools/verify.py (SLOW), config/hooks.json (two protected paths; the hook asks), the four records' rows, the design's §4.5. Shared with lane a: sim/grounding.py and tools/mutants.py (append only), tests/test_transitions.py (read, not edited). sim/world.py and tests/test_simulator.py are not edited. This story starts once #223 (#163) is on main.

    11. Gates. Boundary tests first; export verify with SIM_SEEDS=40; a fresh Claude review and a security pass; AGY (Flash while Argon is out) since sim/ changes; Muse; one fix round; the PR says "Closes #43" and names which invariants the first 40 seeds break nowhere and which faults each seed reaches.

    12. Out of scope. A fork's workflow runs, caches and tokens (#187); the facts and records ports; a Consumer entry that serves issues; the acceptance contract on an issue's draft (the pull request's world has it); a second issue in one world, which no invariant needs.

    Needs the Maintainer? None. The two protected edits, config/hooks.json and the design, are the hook's to ask about, and every model Lens reviews them.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions