Part I Build It The Weekend Sprint

Chapter 1 – The Minimum Viable Factory (Your First Loop)

Build a tiny loop: Terrain → Effector → Map → Validator.

You’ll have it running in less than an hour. We’ll keep the vocabulary plain until you’ve seen it run, then we’ll name the parts so we can reuse them precisely.

Quick Bootstrap: MVF v0 (Map-Terrain sync)

We’re going to build a weekend-grade factory that proves the substrate:

one bounded surface of truth (Terrain)
one versionable intent surface (Map)
one Effector that proposes a patch
one Validator that enforces alignment

In MVF v0, intent is implicit: it’s hard-coded into CLI flags and Make targets. You can think of that as a “Mission v0.” In Chapter 7, we promote it into a typed Mission Object you can diff, version, and re-run.

This first loop is deterministic on purpose. It lets you see the mechanics without keys, SDKs, or network calls. Later, you can swap in a stochastic Effector and keep everything else unchanged.

Copy/paste and run

Copy the block below into an empty directory and run it. It creates a factory/ and product/, plus a tiny Map/Terrain demo surface.

To keep Chapter 1 readable, the full source for the two MVF tools lives in Appendix C. Before running the loop, create these files from Appendix C → “MVF v0: demo tools (full source)”:

factory/tools/sync_public_interfaces.py (Effector)
factory/tools/validate_map_alignment.py (Validator)

Notes:

If git commit fails because Git can’t identify you, set a local identity in the demo repo:
```
git config user.email "you@example.com"
git config user.name "Your Name"
```
The sample Makefile later uses a GNU Make feature to avoid tab-indented recipes. If your make doesn’t support it, use a newer GNU Make (often gmake).

mkdir -p factory/tools product/src product/docs

cat > product/src/tax_calculator.py <<'PY'
def normalize_country(country: str) -> str:
    return country.strip().upper()


def calculate_tax(amount: float, country: str, rate: float) -> float:
    normalized = normalize_country(country)
    return amount * rate
PY

cat > product/docs/architecture.md <<'MD'
# Architecture

## Public Interfaces

- (generated)

## Notes

This file is the Map surface for the MVF demo.
MD

git init -q
git add -A
git commit -m "MVF v0 seed" -q

Now run the loop:

python3 factory/tools/sync_public_interfaces.py --src product/src --doc product/docs/architecture.md --apply
python3 factory/tools/validate_map_alignment.py --src product/src --doc product/docs/architecture.md
git diff --stat || true

What the tools do (interfaces + flow)

The two scripts are intentionally small and deterministic.

Effector interface:

python3 factory/tools/sync_public_interfaces.py --src <terrain_dir> --doc <map_file> [--apply]

Validator interface:

python3 factory/tools/validate_map_alignment.py --src <terrain_dir> --doc <map_file>

Logic flow (sketch):

# Effector
sigs = extract_public_signatures(src)
after = rewrite_public_interfaces_block(doc_text, sigs)
print(unified_diff(before, after))
if apply:
    write(after)

# Validator
terrain = extract_public_signatures(src)
map_sigs = parse_signatures_from_public_interfaces(doc_text)
assert sets_match(terrain, map_sigs)

You now have a minimal loop that (1) senses drift, (2) proposes a patch, (3) applies it inside a bounded Map surface, and (4) proves Map/Terrain alignment with a deterministic Validator.

Re-run the last three commands to confirm idempotence: the Effector should report no drift and the Validator should pass.

Put it behind `make` (recommended)

This chapter uses direct commands so you can see the moving parts. In practice, you want a self-documenting control surface.

Create a Makefile:

.RECIPEPREFIX := >
.PHONY: all sync validate

SRC := product/src
DOC := product/docs/architecture.md

all: sync validate

sync: ## Propose/apply Map updates from Terrain
> python3 factory/tools/sync_public_interfaces.py --src $(SRC) --doc $(DOC) --apply

validate: ## Enforce Map/Terrain alignment (Physics)
> python3 factory/tools/validate_map_alignment.py --src $(SRC) --doc $(DOC)

Now you can run make all and get the same loop with a stable interface.

Hardening ladder: MVF v0 → v1 → v2

The factory grows by adding Physics and governance, not by widening autonomy.

MVF v0 (Weekend): Foreground loop, one narrow Effector, one Validator, one trace in Git.
MVF v1 (Week): Introduce explicit Mission Objects and bounded stochastic changes under hard gates.
MVF v2 (Month): Scheduled runs (Dream Daemon), Map-Updaters, and Immutable Infrastructure boundaries that protect graders and guardrails.

Naming the parts (the canon)

You just ran an Effector and a Validator against a real boundary. In SDaC we give these pieces names so we can reason about them and build tooling around them.

product/src/ → Terrain (runnable reality)
product/docs/architecture.md → Map (versioned intent surface)
Git → Ledger (the history of diffs and decisions)
sync_public_interfaces.py → Effector (proposes/applies a patch)
validate_map_alignment.py → Validator (enforces PASS/FAIL)

You do not need all of these terms on page one. You can keep thinking “code / doc / change script / check” for now. But the canonical names will show up throughout the book.

Terrain = code (runnable reality)

The product/src/ directory is our Terrain: the code that actually runs.

Map = versioned intent surface

The product/docs/architecture.md file is our Map: a structured representation of the Terrain that we can keep aligned.

Version control = Ledger (audit trail)

Git is the Ledger. Every commit records a transaction: what changed, when, and by whom. In a real SDaC system, each automated run also records provenance: which Mission Object, which inputs, which validators, and which outputs.

Effector = bounded change proposer

The sync tool is an Effector: it observes Terrain and proposes a patch to a Map surface. Later, you can put a model call inside an Effector, but the contract stays the same: output a diff, then prove it admissible.

Checker = Validator (blocks bad changes)

The validator script is a Validator. It validates alignment between Map and Terrain. If it fails, the diff is blocked. No debates. No “looks fine.”

The Loop in Action

What you’ve built is a fundamental loop:

Edit the Terrain: you change code in product/src/.
Run the Effector: make sync proposes/applies a patch to the Map surface in product/docs/architecture.md. A git diff shows the change.
Run the Validator: make validate enforces whether Map and Terrain are aligned.
Diff & gate: If the validator passes, you can commit the change to the Ledger. If it fails, the change is blocked and you refine.

This loop gives you deterministic context (the Map), deterministic gates (the Validators), and verifiable loops (the Git Ledger and CI feedback). It tames the stochastic nature of GenAI by wrapping it in engineering rigor.

At this point, you have a working factory. It’s minimal, but it demonstrates the core components.

Actionable: What you can do this week

Run the MVF v0 bootstrap: copy/paste the block above, copy the two MVF tools from Appendix C, then run:
```
make all
```
Break it (create drift):
- Add a new public function to product/src/tax_calculator.py (for example def tax_rate(country: str) -> float: ...).
- Run only the validator:
```
make validate
```
It should fail with missing_in_map=[...].
Fix it (restore alignment):
- Run make sync and then make validate again.
- Inspect the diff:
```
git diff
```
Harden one step:
- Add one more Validator (formatting, type checks, or a schema Validator) and make all depend on it.

This is the shape of the Minimum Viable Factory: small blast radius, concrete diffs, and PASS/FAIL gates.