The regeneration bundle

import subprocess
import sys
import tempfile
from pathlib import Path

from spotregen import make_sample_repo

tmp = tempfile.TemporaryDirectory()
root = make_sample_repo(Path(tmp.name) / "demo")


def spotregen(*args, drop=None):
    """Run `spotregen` in the sample repository; show the call and its output."""
    done = subprocess.run(
        [sys.executable, "-m", "spotregen", *args],
        cwd=root,
        capture_output=True,
        text=True,
        check=False,
    )
    print("$ spotregen", *args)
    lines = (done.stdout + done.stderr).splitlines()
    print("\n".join(x for x in lines if not (drop and drop in x)))
    print(f"[exit {done.returncode}]")

Definition 1 (The regeneration bundle) spotregen context UNIT writes everything a generator needs and nothing it must not copy: the architecture (allowed imports, conventions, open choices, pace policy), the unit’s purpose and intent, the decisions behind it, the public contract (signatures and docstrings, no bodies), the source of its durable evaluations and its consumers.

Example 1 (The outline of a bundle)  

done = subprocess.run(
    [sys.executable, "-m", "spotregen", "context", "core.calc"],
    cwd=root,
    capture_output=True,
    text=True,
    check=True,
)
bundle = done.stdout
print("\n".join(line for line in bundle.splitlines() if line.startswith("#")))

# Regeneration bundle: samplepkg.core.calc
## Purpose
## Architecture (compilation target)
## Intent
### C-1 (contract)
## Provenance
### why-add: Addition is needed
## Public contract (signatures and docstrings, no bodies)
## Durable evaluations
## Consumers (must keep working)

Example 2 (The contract without the implementation)  

start = bundle.index("## Public contract")
print(bundle[start : bundle.index("## Durable evaluations")])
print("implementation leaked:", "return a + b" in bundle)

## Public contract (signatures and docstrings, no bodies)

```python
"""Calculator."""


def add(a: int, b: int) -> int:
    """Add two numbers."""
    ...
```


implementation leaked: False

The bundle shows def add(a: int, b: int) -> int with its docstring and a ... body; the private _helper is absent.

Example 3 (Write it to a file and record its hash)  

import hashlib

spotregen("context", "core.calc", "-o", "bundle.md")
data = (root / "bundle.md").read_bytes()
print(hashlib.sha256(data).hexdigest()[:16], len(data), "bytes")

$ spotregen context core.calc -o bundle.md
wrote bundle.md
[exit 0]
de3dda0ee0fb0960 1348 bytes

The bundle is deterministic Markdown. The drivers record its SHA-256 (bundle_sha256 in run.toml), so a run can be tied to the exact input it was given. Bundles are byte-identical across spotregen releases.

NoteA regenerated file is accepted when

pytest -m regen and the unit’s own tests pass and spotregen check stays clean. The pace of the unit decides what else is needed (see the [pace] table of the architecture). When the generator hits an ambiguity, fix the spec first; do not patch the generated code.

To let an LLM do the generation, see the drivers. Next: compaction.