From 666b159d0b551bc13e72d2c32b15298363fe325e Mon Sep 17 00:00:00 2001 From: Michael Cahill Date: Wed, 11 Mar 2026 20:05:54 -0700 Subject: [PATCH 1/3] docs(M09): add full M09 plan Made-with: Cursor --- docs/milestones/M09/M09_plan.md | 256 ++++++++++++++++++++++++++- docs/milestones/M09/M09_toolcalls.md | 5 +- 2 files changed, 258 insertions(+), 3 deletions(-) diff --git a/docs/milestones/M09/M09_plan.md b/docs/milestones/M09/M09_plan.md index 34795560a..2faf52705 100644 --- a/docs/milestones/M09/M09_plan.md +++ b/docs/milestones/M09/M09_plan.md @@ -1,3 +1,255 @@ -# M09 Plan — Execution Context Seam +# M09 Plan — Execution Context Introduction -(To be populated.) +Project: **Serena** +Phase: **Phase II — Runtime Seam Preparation** +Milestone: **M09** +Title: **Execution Context Introduction** + +Branch: `m09-execution-context` + +--- + +## 1. Intent / Target + +M08 migrated runtime reads from `shared.opts` to `p.opts_snapshot` inside the generation pipeline. + +However the runtime still depends heavily on **global shared state**: + +- `shared.sd_model` +- `shared.device` +- `shared.state` +- `shared.cmd_opts` + +These globals prevent the generation pipeline from becoming a **testable runtime component**. + +The goal of **M09** is to introduce a **lightweight runtime execution context** that groups these runtime dependencies together. + +Example concept: + +```python +RuntimeContext( + model, + opts_snapshot, + device, + state, + cmd_opts +) +``` + +The context will be **attached to the processing object** but will **not yet replace global state everywhere**. + +This milestone introduces the seam without changing behavior. + +--- + +## 2. Scope Boundaries + +### In Scope + +Create a new runtime structure: + +``` +modules/runtime_context.py +``` + +Define `RuntimeContext` with fields: + +- `model` +- `opts_snapshot` +- `device` +- `state` +- `cmd_opts` + +Attach it during generation: + +``` +p.runtime_context +``` + +Initial wiring occurs in `process_images_inner()`: + +```python +p.runtime_context = RuntimeContext( + model=shared.sd_model, + opts_snapshot=p.opts_snapshot, + device=shared.device, + state=shared.state, + cmd_opts=shared.cmd_opts, +) +``` + +Place this **after snapshot creation**. + +### Out of Scope + +M09 must **NOT**: + +- remove `shared.sd_model` +- remove `shared.device` +- modify extension interfaces +- change sampling behavior +- change API responses +- refactor the sampler pipeline + +The context exists **in parallel with shared state** for now. + +--- + +## 3. Invariants + +The following must remain identical. + +| Invariant | Description | +|-----------|-------------| +| Generation determinism | Same inputs → same outputs | +| Sampling math | No changes to samplers or conditioning | +| File outputs | Paths and naming unchanged | +| Extension compatibility | Extensions must still use `shared.*` | +| API behavior | txt2img/img2img responses unchanged | +| CLI behavior | No change to CLI flags | + +--- + +## 4. Verification Plan + +CI gates must remain green. + +| Check | Requirement | +|-------|-------------| +| Linter | Pass | +| Smoke tests | Pass | +| Quality tests | Pass | +| Coverage | ≥ 40% | + +Local verification: + +``` +pytest test/smoke +pytest test/quality +``` + +Manual checks: + +- txt2img generation +- img2img generation +- highres fix +- image saving +- grid saving + +--- + +## 5. Implementation Steps + +### Step 1 — Create runtime context module + +Create file: `modules/runtime_context.py` + +```python +from dataclasses import dataclass + +@dataclass +class RuntimeContext: + model: object + opts_snapshot: object + device: object + state: object + cmd_opts: object +``` + +### Step 2 — Attach context to processing object + +Modify: `modules/processing.py` + +Inside `process_images_inner()`, after snapshot creation: + +```python +from modules.runtime_context import RuntimeContext + +p.runtime_context = RuntimeContext( + model=shared.sd_model, + opts_snapshot=p.opts_snapshot, + device=shared.device, + state=shared.state, + cmd_opts=shared.cmd_opts, +) +``` + +### Step 3 — No migration yet + +Do **NOT** change runtime reads yet. + +For example this must remain: + +```python +shared.sd_model +shared.device +``` + +The context is introduced but **not yet consumed**. + +--- + +## 6. Risk & Rollback Plan + +Risk level: **Very low** + +Changes introduce a new object but do not change runtime behavior. + +| Risk | Mitigation | +|------|------------| +| Missing import | CI smoke tests | +| Attribute collision | Use `runtime_context` name | + +Rollback: `git revert milestone commit` + +--- + +## 7. Deliverables + +Expected code changes: + +- `modules/runtime_context.py` (new) +- `modules/processing.py` (modified) + +Documentation artifacts: + +- `docs/milestones/M09/M09_plan.md` +- `docs/milestones/M09/M09_toolcalls.md` + +--- + +## 8. Expected Outcome + +After M09 the generation runtime will expose `p.runtime_context` which groups: + +- `model` +- `opts_snapshot` +- `device` +- `state` +- `cmd_opts` + +The runtime seam stack becomes: + +``` +temporary_opts() M05 +prepare_prompt_seed_state() M06 +opts snapshot M07 +snapshot threading M08 +execution context M09 +``` + +This completes **Phase II runtime seam preparation**. + +--- + +## 9. Success Criteria + +M09 is complete when: + +- [ ] Runtime context introduced +- [ ] Context attached to processing object +- [ ] CI fully green +- [ ] No behavior change +- [ ] Milestone artifacts generated +- [ ] Ledger updated +- [ ] Tag created: `v0.0.09-m09` diff --git a/docs/milestones/M09/M09_toolcalls.md b/docs/milestones/M09/M09_toolcalls.md index 1c2f1f788..0c39211fd 100644 --- a/docs/milestones/M09/M09_toolcalls.md +++ b/docs/milestones/M09/M09_toolcalls.md @@ -2,4 +2,7 @@ Implementation toolcalls for Cursor execution. -(To be filled during milestone execution.) +| Timestamp | Tool | Purpose | Files/Target | Status | +|-----------|------|---------|--------------|--------| +| 2026-03-11 | write | Populate M09_plan.md with full plan | docs/milestones/M09/M09_plan.md | completed | +| 2026-03-11 | run | git checkout main, pull, create branch | git | pending | From 372e0673f3d344029988df1e308742a4095a9384 Mon Sep 17 00:00:00 2001 From: Michael Cahill Date: Wed, 11 Mar 2026 20:06:35 -0700 Subject: [PATCH 2/3] feat(M09): introduce RuntimeContext and attach to processing object - Add modules/runtime_context.py with RuntimeContext dataclass - Attach p.runtime_context in process_images_inner() after opts_snapshot - Write-only: no migration of shared.* reads yet - Completes Phase II runtime seam preparation Made-with: Cursor --- docs/milestones/M09/M09_toolcalls.md | 6 +++++- modules/processing.py | 8 ++++++++ modules/runtime_context.py | 18 ++++++++++++++++++ 3 files changed, 31 insertions(+), 1 deletion(-) create mode 100644 modules/runtime_context.py diff --git a/docs/milestones/M09/M09_toolcalls.md b/docs/milestones/M09/M09_toolcalls.md index 0c39211fd..057029767 100644 --- a/docs/milestones/M09/M09_toolcalls.md +++ b/docs/milestones/M09/M09_toolcalls.md @@ -5,4 +5,8 @@ Implementation toolcalls for Cursor execution. | Timestamp | Tool | Purpose | Files/Target | Status | |-----------|------|---------|--------------|--------| | 2026-03-11 | write | Populate M09_plan.md with full plan | docs/milestones/M09/M09_plan.md | completed | -| 2026-03-11 | run | git checkout main, pull, create branch | git | pending | +| 2026-03-11 | run | git checkout main, pull, create branch | git | completed | +| 2026-03-11 | write | Create modules/runtime_context.py | modules/runtime_context.py | completed | +| 2026-03-11 | search_replace | Attach RuntimeContext in process_images_inner | modules/processing.py | completed | +| 2026-03-11 | run | pytest test/smoke | test/smoke | pending | +| 2026-03-11 | run | pytest test/quality | test/quality | pending | diff --git a/modules/processing.py b/modules/processing.py index 6cc5a7196..6f3d87b30 100644 --- a/modules/processing.py +++ b/modules/processing.py @@ -27,6 +27,7 @@ import modules.face_restoration import modules.images as images import modules.styles from modules.opts_snapshot import create_opts_snapshot +from modules.runtime_context import RuntimeContext import modules.prompt_seed_prep as prompt_seed_prep import modules.runtime_utils as runtime_utils import modules.sd_models as sd_models @@ -893,6 +894,13 @@ def process_images_inner(p: StableDiffusionProcessing) -> Processed: prompt_seed_prep.prepare_prompt_seed_state(p) p.opts_snapshot = create_opts_snapshot(shared.opts) + p.runtime_context = RuntimeContext( + model=shared.sd_model, + opts_snapshot=p.opts_snapshot, + device=shared.device, + state=shared.state, + cmd_opts=shared.cmd_opts, + ) if os.path.exists(cmd_opts.embeddings_dir) and not p.do_not_reload_embeddings: model_hijack.embedding_db.load_textual_inversion_embeddings() diff --git a/modules/runtime_context.py b/modules/runtime_context.py new file mode 100644 index 000000000..294d9231e --- /dev/null +++ b/modules/runtime_context.py @@ -0,0 +1,18 @@ +"""Runtime execution context for generation runs. + +M09: Lightweight context grouping model, opts_snapshot, device, state, +cmd_opts. Attached to processing object as p.runtime_context. +Write-only in M09; not yet consumed by runtime. +""" +from dataclasses import dataclass + + +@dataclass +class RuntimeContext: + """Groups runtime dependencies for the generation pipeline.""" + + model: object + opts_snapshot: object + device: object + state: object + cmd_opts: object From 398e281d4bc1dc7813a32e689c747bc492286446 Mon Sep 17 00:00:00 2001 From: Michael Cahill Date: Wed, 11 Mar 2026 20:07:11 -0700 Subject: [PATCH 3/3] docs(M09): update toolcalls log Made-with: Cursor --- docs/milestones/M09/M09_toolcalls.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/milestones/M09/M09_toolcalls.md b/docs/milestones/M09/M09_toolcalls.md index 057029767..384efb635 100644 --- a/docs/milestones/M09/M09_toolcalls.md +++ b/docs/milestones/M09/M09_toolcalls.md @@ -8,5 +8,6 @@ Implementation toolcalls for Cursor execution. | 2026-03-11 | run | git checkout main, pull, create branch | git | completed | | 2026-03-11 | write | Create modules/runtime_context.py | modules/runtime_context.py | completed | | 2026-03-11 | search_replace | Attach RuntimeContext in process_images_inner | modules/processing.py | completed | -| 2026-03-11 | run | pytest test/smoke | test/smoke | pending | -| 2026-03-11 | run | pytest test/quality | test/quality | pending | +| 2026-03-11 | run | pytest test/smoke | test/smoke | skipped (local env) | +| 2026-03-11 | run | pytest test/quality | test/quality | skipped (local env) | +| 2026-03-11 | run | git commit, push, gh pr create | git, gh | completed |