# Building an Infospace with History — Tutorial

This tutorial walks through how to build a structured **infospace** from
Adam Smith's *The Wealth of Nations*, mapping classical economic concepts
to Stafford Beer's **Viable System Model** (VSM), using MarkiTect's
infospace tooling.

By the end you will understand how to:

1. Declare an infospace with `infospace.yaml` and `markitect infospace init`
2. Design schemas that scaffold structured LLM output
3. Write prompt templates with dependency injection (`@{macro}` syntax)
4. Run an incremental, chapter-by-chapter pipeline
5. Evaluate entity quality and run collection-level checks
6. Review viability against declared thresholds
7. Track every change through git history
8. Use a completed infospace as a discipline for a new project

---

## 1. What Is an Infospace?

An **infospace** is a curated, self-describing collection of **entities**
(concepts, mechanisms, observations) that together explain a **topic**
through the lens of one or more **disciplines**.

| Term | This example |
|---|---|
| Topic | *The Wealth of Nations* (Smith, 1776) |
| Discipline | Viable System Model (Beer) |
| Entities | Economic concepts: division of labour, natural price, … |
| Viability | Does the entity set answer the competency questions? |

The challenge with a large source corpus is that it is too big for a single
prompt. MarkiTect processes it **incrementally**, one chapter at a time,
building up the entity set and tracking progress through git.

An infospace is **viable** when it meets threshold scores across defined
metrics — it is fit for purpose as an explanatory tool.

---

## 2. Project Layout

```
examples/infospace-with-history/
│
├── infospace.yaml              # Declarative infospace configuration (NEW)
├── README.md
├── TUTORIAL.md                 # This file
├── INFRA-TASKS.md              # Infrastructure issues found during the experiment
├── process_chapters.py         # Pipeline script (chapter processing)
├── infospace.db                # SQLite artifact database (generated, not in git)
│
├── schemas/                    # Output structure definitions
│   ├── economic-entity-schema-v1.0.md
│   ├── vsm-concept-schema-v1.0.md
│   ├── vsm-mapping-schema-v1.0.md
│   └── chapter-analysis-schema-v1.0.md
│
├── templates/                  # Prompt templates (with @{macro} placeholders)
│   ├── extract-entities.md
│   ├── map-to-vsm.md
│   ├── synthesize-analysis.md
│   └── assess-metrics.md
│
├── artifacts/                  # Input artifacts
│   ├── sources/                # Chapter text (35 files)
│   ├── guidelines/             # Extraction and mapping rules
│   └── vsm-reference/         # VSM framework definition
│
└── output/                     # Generated artifacts (LLM outputs)
    ├── entities/               # Flat canonical entity set + chapter views
    │   ├── division-of-labour.md        # Canonical entity file (PRIMARY)
    │   ├── exchange.md
    │   ├── book-1-chapter-01-entities.md  # Chapter view (transclusion)
    │   └── ...
    ├── mappings/               # Per-chapter VSM mappings
    ├── analyses/               # Per-chapter synthesised analyses
    └── metrics/                # Collection metrics + history
        ├── metrics.yaml        # Latest metric values
        └── history.yaml        # Timestamped snapshot log
```

**Entity organisation**: The infospace maintains a **flat canonical set**
of entities — one markdown file per entity in `output/entities/`. Duplicate
slugs across chapters are skipped (first occurrence wins). Per-chapter
`*-entities.md` files are **secondary views** using transclusion directives
(`{{ include "entity.md" }}`), so editing a canonical file updates every
chapter view that references it.

---

## 3. Initialising an Infospace

### Starting fresh

Use `markitect infospace init` to create an `infospace.yaml`:

```bash
cd my-new-infospace/
markitect infospace init \
  --topic "The Wealth of Nations" \
  --domain "Classical Economics" \
  --sources artifacts/sources/ \
  --discipline "Viable System Model"
```

This creates a minimal `infospace.yaml`. Edit it to add schemas,
competency questions, and viability thresholds:

```yaml
topic:
  name: "The Wealth of Nations"
  domain: "Classical Economics"
  sources: artifacts/sources/

disciplines:
  - name: "Viable System Model"
    path: artifacts/vsm-reference/

schemas:
  entity: schemas/economic-entity-schema-v1.0.md
  mapping: schemas/vsm-mapping-schema-v1.0.md
  analysis: schemas/chapter-analysis-schema-v1.0.md

competency_questions: |
  1. How does Smith's division of labour map to VSM System 1 operations?
  2. What mechanisms in WoN correspond to VSM coordination (System 2)?
  3. Where does Smith describe self-organising regulation (System 3)?
  4. What role does the "invisible hand" play as a System 4 mechanism?
  5. How do Smith's views on government map to System 5 policy?
  6. Is the WoN entity set viable as an explanatory framework?

viability:
  redundancy_ratio: { max: 0.10 }
  coverage_ratio: { min: 0.50 }
  coherence_components: { max: 3 }
  consistency_cycles: { max: 0 }
  granularity_entropy: { min: 1.0 }

pipeline:
  stages:
    - name: extract-entities
      template: templates/extract-entities.md
    - name: map-to-vsm
      template: templates/map-to-vsm.md
    - name: synthesize-analysis
      template: templates/synthesize-analysis.md
```

### Checking status

At any point, inspect the infospace:

```bash
markitect infospace status
# Infospace: The Wealth of Nations
# Domain:    Classical Economics
# Entities:  109
# Domains:   Production, Distribution, Exchange, Regulation
# Disciplines: Viable System Model
# Chapters:  9/35 processed

markitect infospace entities
# Lists all entities with domain, source chapter, word count
```

---

## 4. Designing Schemas

Before writing any prompts, define **schemas** — markdown documents that
tell the LLM exactly what sections each output must contain. Schemas are
not code; the LLM reads them as instructions.

### Economic Entity Schema (`schemas/economic-entity-schema-v1.0.md`)

Every extracted entity must have:

- **H1 heading** with the entity name (title case)
- **Definition** (20–150 words, precise and non-circular)
- **Source Chapter** citing Book and Chapter
- **Context** — where in Smith's argument the entity appears
- **Economic Domain** (Production, Distribution, Exchange, etc.)

Optional: Smith's Original Wording, Modern Interpretation.

### VSM Mapping Schema (`schemas/vsm-mapping-schema-v1.0.md`)

Every entity-to-VSM mapping must have:

- **H1 heading**: `Entity Name -> VSM Concept Name`
- **Economic Entity Reference** and **VSM Concept Reference**
- **Mapping Rationale** (minimum 30 words, grounded in Beer's definitions)
- **Mapping Strength**: Strong, Moderate, or Weak

### Chapter Analysis Schema (`schemas/chapter-analysis-schema-v1.0.md`)

The per-chapter synthesis includes:

- **Chapter Summary** (50–300 words)
- **Entities Extracted** — bulleted list
- **VSM Mappings** — entity, concept, strength
- **VSM Coverage** — explicit assessment of S1 through S5 and S3*
- **Gaps & Observations**

**Key insight**: Schemas are artifacts — they live in the repository and
can be versioned, diffed, and refined just like code. Improving a schema
and re-processing a chapter is visible as a git diff.

---

## 5. Writing Prompt Templates

Each template is a markdown file with `@{macro_name}` placeholders that
MarkiTect's resolver fills with artifact content at compile time.

### Template 1: Extract Entities (`templates/extract-entities.md`)

```markdown
# Extract Economic Entities

You are an analytical economist specialising in classical economic theory.
Your task is to extract distinct economic entities from a chapter of
Adam Smith's *The Wealth of Nations*.

## Source Chapter
@{chapter_text}

## Extraction Guidelines
@{extraction_rules}

## VSM Framework Context
@{vsm_framework}

## Existing Entities
@{existing_entities}

## Output Format
Output each entity delimited by `--- ENTITY: <entity-name> ---` markers.
```

The `@{existing_entities}` macro is generated at runtime from canonical
files already on disk, enabling incremental extraction without duplication.

### Template 2: Map to VSM (`templates/map-to-vsm.md`)

Inputs: `@{entities}`, `@{vsm_framework}`, `@{mapping_rules}`.

### Template 3: Synthesise Analysis (`templates/synthesize-analysis.md`)

Inputs: `@{chapter_text}`, `@{entities}`, `@{mappings}`, `@{vsm_framework}`.

### Template 4: Assess Metrics (`templates/assess-metrics.md`)

Inputs: `@{all_analyses}` (all chapter analyses concatenated), `@{vsm_framework}`.
Runs across the entire infospace, not per-chapter.

**Dependency chain per chapter:**

```
chapter_text ─────┐
extraction_rules ──┤
vsm_framework ────┤
                   ▼
           extract-entities
                   │
                   ▼ entities
           map-to-vsm
                   │
                   ▼ mappings
           synthesize-analysis
                   │
                   ▼ analysis
```

---

## 6. Populating Artifacts

### Source chapters (`artifacts/sources/`)

35 markdown files with the full public-domain text of each chapter.
Named `book-1-chapter-01.md` through `book-5-chapter-03.md`.

### Guidelines (`artifacts/guidelines/`)

- **`extraction-rules.md`** — What constitutes an entity, granularity
  rules, naming conventions.
- **`mapping-rules.md`** — How to map entities to VSM systems, what
  constitutes Strong/Moderate/Weak strength.

### VSM reference (`artifacts/vsm-reference/`)

- **`vsm-framework.md`** — Complete description of Beer's VSM (S1–S5,
  S3*, recursion, variety, viability, algedonic signals, autonomy) with
  economic interpretations.

---

## 7. Processing Chapters

`process_chapters.py` orchestrates the three-stage pipeline. It initialises
the artifact repository, loads static artifacts, runs entity extraction →
VSM mapping → analysis synthesis, and commits each chapter to git.

### Single chapter

```bash
# Manual mode (writes prompts, awaits output files):
python process_chapters.py --chapter book-1-chapter-05 --no-commit

# Auto mode via OpenRouter (free models available):
python process_chapters.py --chapter book-1-chapter-05 --provider openrouter

# With a specific free model:
python process_chapters.py --chapter book-1-chapter-05 \
  --provider openrouter --model meta-llama/llama-4-maverick:free
```

### Whole book or all chapters

```bash
python process_chapters.py --book 1 --provider openrouter
python process_chapters.py --all --provider openrouter
```

### Check progress

```bash
python process_chapters.py --list
```

```
Available chapters (35):

  Chapter                        Entities     Mappings     Analysis
  ------------------------------ ------------ ------------ ------------
  book-1-chapter-01              done (13)    done         done
  book-1-chapter-02              done (7)     done         done
  ...

  Canonical entity set: 109 unique entities
```

### Entity lifecycle

Entities in the canonical set are **never silently deleted**. Retire
an entity by archiving it with a documented reason:

```bash
python process_chapters.py --archive-entity enlarged-monopoly \
  --reason "Subsumed by monopoly-price — same market distortion"
```

The archived file moves to `output/entities/archive/<slug>.md` with a
dated header, preserving the intellectual history of every decision.

---

## 8. Evaluating Entity Quality

Once chapters are processed, evaluate the entity set using the infospace
tooling commands.

### Per-entity evaluation

```bash
# Evaluate all entities (requires LLM provider):
markitect infospace evaluate --provider openrouter

# Evaluate entities from a specific chapter:
markitect infospace evaluate --chapter book-1-chapter-05 --provider openrouter

# Re-evaluate a single entity:
markitect infospace evaluate --entity division-of-labour --provider openrouter
```

This runs the `evaluate-entity` prompt template against each entity,
scoring dimensions like definition precision, source grounding, and
VSM relevance. Results are written to `output/evaluations/`.

### Collection-level checks (C1–C5)

```bash
# Run all five collection checks:
markitect infospace check --provider openrouter

# Run individual checks:
markitect infospace check redundancy   # C1: Are any entities synonymous?
markitect infospace check coverage     # C2: Which domain × VSM cells are empty?
markitect infospace check coherence    # C3: Is the entity graph well-connected?
markitect infospace check consistency  # C4: Are there circular definitions?
markitect infospace check granularity  # C5: Is abstraction level balanced?
```

Each check uses the platform's embedding, graph analysis, and FCA
infrastructure. Results are written to `output/metrics/` and a new
snapshot is appended to `metrics-history.yaml`.

Sample output:

```
Running collection checks on 109 entities...

  C1 — redundancy
    redundancy_ratio: 0.0183
    high_similarity_pairs: 2

  C2 — coverage
    coverage_ratio: 0.4286
    empty_cells: [['Regulation', 'S3*'], ['Historical', 'S5']]

  C3 — coherence
    coherence_components: 1
    modularity: 0.412

  C4 — consistency
    consistency_cycles: 0
    grounding_ratio: 0.94

  C5 — granularity
    granularity_entropy: 2.69
```

---

## 9. Reviewing Viability

```bash
markitect infospace viability
```

Compares the latest metrics against the thresholds declared in
`infospace.yaml`:

```
Metric                         Value    Threshold   Status
-----------------------------------------------------------
redundancy_ratio               0.0183    max=0.10     PASS
coverage_ratio                 0.4286    min=0.50     FAIL
coherence_components           1         max=3        PASS
consistency_cycles             0         max=0        PASS
granularity_entropy            2.6900    min=1.0      PASS

Viable: NO (4/5 thresholds met)
```

Coverage is currently failing (42% < 50% threshold) because only 9 of
35 chapters have been processed. Once more chapters are done, coverage
will rise.

### Metrics history

```bash
markitect infospace history
```

Shows how metrics evolved across runs:

```
Snapshot  Date        Entities  coverage  redundancy  entropy
-------------------------------------------------------------
6ba48eb2  2026-02-19  85        0.361     0.000       2.687
```

---

## 10. Tracking History with Git

Every processed chapter produces one git commit containing:

- Compiled prompts (`*-prompt.md`) — audit what was sent to the LLM
- Canonical entity files (`output/entities/<slug>.md`) — first occurrence wins
- Chapter entity views (`<chapter>-entities.md`) — transclusion references
- Generated outputs (`*-mappings.md`, `*-analysis.md`)

This means:

- `git log` shows the chronological order of processing
- `git diff` between commits shows what each chapter contributed
- You can `git bisect` to find where quality degraded
- You can revert a chapter and re-process with improved guidelines

The `clean-example-history` branch in this repository demonstrates the
intended structure: each chapter is a single, self-contained commit.
Use it as a reference for how the infospace grew step by step.

To commit manually after reviewing:

```bash
python process_chapters.py --chapter book-1-chapter-05 --provider openrouter --no-commit
# review output/entities/ and output/mappings/
git add examples/infospace-with-history/output/
git commit -m "infospace: process book-1-chapter-05"
```

---

## 11. Cost and Performance

| | OpenRouter (free) | OpenRouter (paid) | Gemini (free) |
|---|---|---|---|
| Time per chapter | ~5 min | ~2 min | ~45 sec |
| Cost per chapter | $0.00 | ~$0.07 | $0.00 |
| Default model | `arcee-ai/trinity-large-preview:free` | `anthropic/claude-sonnet-4` | `gemini-2.5-flash` |
| Rate limits | ~200 req/day | High | Per-minute |

**OpenRouter free tier**: Sign up at [openrouter.ai](https://openrouter.ai)
(no credit card required). Store your key in `apikey-openrouter.txt` in the
project root (git-ignored), or set `OPENROUTER_API_KEY`.

```bash
export OPENROUTER_API_KEY=$(cat apikey-openrouter.txt | tr -d '[:space:]')
```

Use `openrouter/free` to automatically select from whichever free model is
available:

```bash
python process_chapters.py --chapter book-1-chapter-05 \
  --provider openrouter --model openrouter/free
```

**Gemini free tier**: Get a key at [aistudio.google.com/apikey](https://aistudio.google.com/apikey),
store in `apikey-geminifree.txt`.

Note: The `claude-code` provider (Claude CLI subprocess) is not available
when running inside a Claude Code session due to nested session restrictions.

---

## 12. Completing the Remaining Chapters

As of writing, 9 of 35 chapters are processed (Book I, Chapters 1–9).

**Process Book I remainder:**

```bash
export OPENROUTER_API_KEY=$(cat apikey-openrouter.txt | tr -d '[:space:]')
git checkout clean-example-history
python process_chapters.py --book 1 --provider openrouter
```

Already-processed chapters are skipped — their chapter view files exist.
The `@{existing_entities}` macro ensures the LLM only extracts genuinely
new entities.

**Process Books II–V:**

```bash
python process_chapters.py --book 2 --provider openrouter
python process_chapters.py --book 3 --provider openrouter
python process_chapters.py --book 4 --provider openrouter
python process_chapters.py --book 5 --provider openrouter
```

**Run collection checks after each book:**

```bash
markitect infospace check --provider openrouter
markitect infospace viability
```

**Expected progression:**

| After | Chapters | Expected coverage |
|-------|----------|-------------------|
| Book I (11 ch.) | 11/35 | S1, S2, S4 strong; S3 emerging |
| Books I–II (16 ch.) | 16/35 | S3 (capital control) covered |
| Books I–III (20 ch.) | 20/35 | Historical patterns add depth |
| Books I–IV (30 ch.) | 30/35 | S5 (policy, mercantilism) emerging |
| All (35 ch.) | 35/35 | Full coverage; S3* and algedonic signals from Book V |

---

## 13. Using the Infospace as a Discipline

A completed, viable infospace can itself become a **discipline** — a lens
applied to a new topic. For example, the Wealth of Nations infospace could
be applied to analyse a modern supply chain.

```bash
# In a new infospace directory:
markitect infospace init \
  --topic "Modern Supply Chain Management" \
  --domain "Operations Research" \
  --discipline "Wealth of Nations"

# Bind the WoN infospace as a discipline:
markitect infospace bind-discipline ../infospace-with-history

# List bound disciplines and their viability:
markitect infospace disciplines
# Viable System Model    PASS (from vsm-reference/)
# Wealth of Nations      PASS (from ../infospace-with-history)

# Check for stale mappings after discipline update:
markitect infospace stale-mappings
```

The discipline infospace must be viable (meeting its own thresholds)
before it can be used as a lens. If the discipline's entities change,
dependent mappings are flagged for re-evaluation.

---

## 14. Quality Improvement Loop

The infospace is designed to be **iteratively refined**:

1. **Process chapters** — run the pipeline
2. **Evaluate** — `markitect infospace evaluate --provider openrouter`
3. **Check** — `markitect infospace check --provider openrouter`
4. **Review viability** — `markitect infospace viability`
5. **Refine guidelines** — update `extraction-rules.md` or
   `mapping-rules.md` to address identified weaknesses
6. **Re-process** — delete output files for specific chapters and re-run
7. **Compare** — `git diff` shows how refined guidelines changed the output

Example: if checks show S3* (Audit) is consistently missing, add a
paragraph to `extraction-rules.md` explicitly asking the LLM to look for
audit, inspection, and oversight mechanisms.

To re-process a specific chapter:

```bash
rm -f output/entities/book-1-chapter-03-entities.md
rm -f output/mappings/book-1-chapter-03-mappings.md
rm -f output/analyses/book-1-chapter-03-analysis.md
python process_chapters.py --chapter book-1-chapter-03 --provider openrouter
```

Never silently delete canonical entity files. Archive them instead:

```bash
python process_chapters.py --archive-entity extent-of-the-market \
  --reason "Subsumed by market-price and effectual-demand"
python process_chapters.py --chapter book-1-chapter-03 --provider openrouter
```

---

## 15. The Artifact Database (`infospace.db`)

The pipeline stores all artifacts and dependency edges in a local SQLite
database — `infospace.db`. This file is **not committed to git** because
it is fully derived from the markdown files that are tracked.

To regenerate it after a fresh clone (no LLM calls needed):

```bash
python process_chapters.py --all --no-commit
```

---

## 16. Adapting This Pattern to Your Own Project

To build your own infospace:

1. `markitect infospace init --topic "..." --domain "..." --discipline "..."`
2. Write schemas defining required sections for each output type
3. Write extraction guidelines that tell the LLM what to look for
4. Create prompt templates using `@{macro}` syntax
5. Populate `artifacts/sources/` with your source corpus
6. Run `process_chapters.py` (or your equivalent pipeline script)
7. Evaluate with `markitect infospace evaluate` and `check`
8. Review `markitect infospace viability` against your thresholds
9. Iterate: refine guidelines, re-process, re-evaluate
10. Once viable, use as a discipline for a new infospace

The key insight is that **schemas and guidelines are artifacts** — they
live in the repository and can be versioned and diffed just like code.
Every refinement decision is traceable through git history.

---

## 17. Observing Entity Heterogeneity

After processing all 35 chapters you will notice that the entity collection
is not homogeneous. Reviewing the files, some entities describe **things
that exist** (stocks, agents, institutions) while others describe **how
things connect** (mechanisms, signals, causal dependencies):

| Entity | Character |
|---|---|
| *Capital Stock* | A persistent resource — an element |
| *Division of Labour* | An ongoing activity — a process |
| *Natural Price* | A structural dependency — a relation |
| *Opportunity Cost* | An abstract invariant — a principle |
| *Banking System* | A socially constructed rule — an institution |

This heterogeneity is not a flaw in the extraction. It reflects the actual
structure of Smith's argument. But treating all entities identically — as
unnamed nodes in a flat collection — hides structural information that is
necessary for building a systemic model.

The VSM mapping compounds this: System 2 ends up containing both a *price
signal* (a relation) and a *market* (an element that hosts those signals).
Both are genuinely in S2, but conflating them makes it harder to answer the
competency questions precisely.

**The solution is layered development**: moving from the flat entity set
toward a typed, structured, minimal systemic model. The full concept and
rationale is documented in [`LAYERED-DEVELOPMENT.md`](LAYERED-DEVELOPMENT.md).

---

## 18. The Four Layers

Infospace development proceeds through four layers, each with its own
pipeline, schema, and viability check:

```
L0  Source text (35 chapters)
     │  extract-entities
     ▼
L1  Raw entities (~988)          ← current state after full processing
     │  classify-entities
     ▼
L2  Typed entities               Each entity has: type × VSM coordinate
     │  extract-relations
     ▼
L3  Relation graph               Explicit triplets: Element → Relation → Element
     │  distil-core
     ▼
L4  Systemic model               Minimal viable set (~30 elements + 20 relations)
```

Each layer is a **proper infospace** that uses the previous layer as its
topic (and sometimes as its discipline). The composition model already
built into MarkiTect makes this explicit and auditable.

---

## 19. Layer 2 — Classifying Entities

The goal of Layer 2 is to assign every entity a **type** and confirm or
refine its **VSM system assignment**, giving each entity a coordinate in a
structured space.

### Entity types

| Type | What it is | Examples |
|---|---|---|
| **Element** | A stock, agent, or artifact that persists | Capital Stock, Corn, Colony |
| **Process** | A flow or transformation (has duration) | Division of Labour, Trade, Credit Extension |
| **Relation** | A structural dependency between elements | Natural Price, Wages of Labour |
| **Principle** | An abstract law holding across contexts | Comparative Advantage, Opportunity Cost |
| **Institution** | A socially constructed rule system | Banking System, Guild, Taille |

### New schema: `schemas/typed-entity-schema-v1.0.md`

Extend the economic entity schema with two new required sections:

```markdown
## Entity Type

[Element | Process | Relation | Principle | Institution]

## VSM System

[S1 | S2 | S3 | S3* | S4 | S5]
```

And two supporting rationale fields (one sentence each):

```markdown
## Type Rationale

This is a Relation because it expresses a structural dependency between
Wages and Capital Stock rather than being an entity that exists independently.

## VSM Rationale

Assigned to S2 because Natural Price functions as the coordination signal
that prevents market price oscillation — Beer's primary definition of S2.
```

### New pipeline stage: `classify-entities`

Add the stage to `infospace.yaml` after the existing pipeline:

```yaml
pipeline:
  stages:
    - name: extract-entities
      template: templates/extract-entities.md
      output_dir: output/entities
      ...
    - name: map-to-vsm
      ...
    - name: synthesize-analysis
      ...
    - name: classify-entities
      template: templates/classify-entities.md
      output_dir: output/typed-entities
      output_macro: typed_entity
      max_tokens: 1200
      macros:
        vsm_framework: artifacts/vsm-reference/vsm-framework.md
        type_taxonomy: artifacts/guidelines/entity-type-taxonomy.md
```

This stage runs **once per entity** (not per chapter), taking the canonical
entity file as input and producing an enriched version in `output/typed-entities/`.

### New coverage metric — type × VSM matrix

At Layer 2, the coverage metric gains a new interpretation. The matrix is
no longer domain × chapter but **type × VSM system** — a 5 × 6 grid:

```
           S1     S2     S3    S3*    S4     S5
Element    ████   ████   ██    ·      ██     ██
Process    ████   ████   ██    ·      ████   ·
Relation   ████   ████   ████  ██     ██     ██
Principle  ██     ██     ·     ·      ████   ████
Institution·      ·      ████  ████   ·      ████
```

An empty cell in this matrix means the VSM system has no entities of that
structural type — a genuine explanatory gap.

---

## 20. Layer 3 — Extracting the Relation Graph

The goal of Layer 3 is to make the **connections between entities explicit**.
Rather than inferring connectivity from embedding similarity or co-occurrence,
Layer 3 extracts directed, typed **triplets** from entity definitions and
source chapters.

### Triplet structure

Each triplet is a directed edge in the relation graph:

```
Subject             Predicate          Object
──────────────────  ─────────────────  ──────────────────
Division of Labour  ←limited by→       Market Extent
Capital Stock       ←enables→          Division of Labour
Natural Price       ←centres on→       Market Price
Wages of Labour     ←regulated by→     Profit of Stock
```

The predicate is drawn from a **controlled vocabulary** of twelve relation
classes, each mapped to a VSM channel:

| Predicate class | VSM channel |
|---|---|
| enables / constrains | S1 structural dependency |
| regulates / is regulated by | S3→S1 control |
| coordinates | S2 anti-oscillation |
| produces / consumes | S1 operational flow |
| monitors / audits | S3* audit loop |
| adapts to / anticipates | S4 intelligence |
| defines / is defined by | S5 policy authority |
| contradicts / tensions with | cross-level conflict |

### New output directory: `output/relations/`

One file per triplet (or per named relation cluster):

```markdown
# Division of Labour — limited by — Market Extent

## Subject
Division of Labour (Process / S1)

## Predicate
limited by

## Object
Market Extent (Element / S2)

## VSM Channel
S1 operational capacity constrained by S2 coordination reach

## Evidence
Book I, Chapter 3: "The division of labour is limited by the extent
of the market."

## Feedback Role
Entry point of the Market Expansion loop.
```

### Feedback loops

The relation graph will reveal feedback loops — cycles in the directed
graph. These are the most structurally important outputs of Layer 3 because
they are the mechanisms Smith describes throughout the WoN:

```
Capital Accumulation → Division of Labour → Productivity
  → Profit Margin → Capital Accumulation    [positive reinforcement]

Market Price above Natural Price → Capital Inflow → Supply
  → Market Price restores                   [balancing loop, S2]

Wages rise → Consumer Demand → Employment
  → Wages rise                              [positive reinforcement, S1]
```

Finding and naming these loops is the primary intellectual payoff of
Layer 3. Each loop can be documented as a named pattern:

```bash
# Future command:
markitect infospace loops
# Detected feedback loops (3):
#   Capital Accumulation Loop (positive, S1→S3→S1)
#   Price Equilibration Loop  (balancing, S2)
#   Labour Market Loop        (positive, S1→S2→S1)
```

---

## 21. Layer 4 — The Minimal Systemic Model

Layer 4 answers the ultimate question: **what is the smallest set of
elements and relations that can generate Smith's argument from first
principles?**

The hypothesis is that the 988-entity collection can be reduced to a core
of roughly 30–40 elements, 15–25 relations, and 8–12 principles. Everything
else is a refinement, an illustration, or historical context.

### How the core is identified

Two methods work together:

**Graph centrality**: Entities with the highest combined in-degree and
out-degree in the Layer 3 relation graph are candidates. An entity that
many other entities connect to or depend on is structurally load-bearing.

**VSM completeness**: The core must have at least one entity at each VSM
level, and each level must have at least one Element, one Process, and one
Relation. This is the stopping condition — the minimum viable set is the
smallest set that is VSM-complete.

**FCA concept density**: The concept lattice from Layer 1 (FCA already
computed) identifies which entities co-occur across the most attributes
(domains and chapters). High-density concepts are likely core entities.

### Output: `output/core-model.md`

The final artifact documents the core model with explicit VSM assignment,
named feedback loops, and competency question coverage:

```markdown
# Core Systemic Model — The Wealth of Nations (L4)

## Core Elements
### S1 — Operations
- Labour
- Capital Stock
- Land
- Commodity

### S2 — Coordination
- Market

### S3 — Management
- Banking System

## Core Processes
- Division of Labour (S1)
- Agricultural Production (S1)
- Trade (S1)
- Capital Allocation (S3)

## Core Relations
- Natural Price — centres — Market Price (S2)
- Wages of Labour — allocates — Labour (S2)
- Profit of Stock — allocates — Capital (S2)

## Core Principles
- Invisible Hand (S4)
- Comparative Advantage (S4)
- System of Natural Liberty (S5)

## Feedback Loops
1. Capital Accumulation (positive, S1–S3)
2. Price Equilibration (balancing, S2)
3. Labour Market (positive, S1–S2)

## Viability
VSM coverage: S1 ✓  S2 ✓  S3 ✓  S4 ✓  S5 ✓
Competency questions answered: 6/6
Entities in core: 28 / 988 (3%)
```

### What the core enables

With a validated core model, the infospace becomes far more useful as a
discipline:

- **Composability**: Another infospace can import the WoN core as its
  discipline, knowing that only the 28 load-bearing entities will be
  injected as context — not all 988.
- **Gap analysis**: New source material can be evaluated against the core:
  does this modern supply chain text engage with Smith's three core
  relations? If not, the analysis is incomplete.
- **Theory comparison**: Two economic theories (Smith and Ricardo, say)
  can be compared at the core level — do they share elements? Where do
  their feedback loops diverge?

---

## 22. Running Layers 2–4 (Planned)

The following commands are planned for a future implementation phase.
They are documented here to describe the intended workflow.

### Layer 2: classify all entities

```bash
# Classify entity types and confirm VSM assignments:
markitect infospace classify --provider openrouter

# Classify a single entity:
markitect infospace classify --entity division-of-labour --provider openrouter

# Review type × VSM coverage matrix:
markitect infospace check type-coverage
```

Expected output:

```
Classifying 988 entities...
  [████████████████████] 988/988

Type distribution:
  Element:     312 (32%)
  Process:     248 (25%)
  Relation:    201 (20%)
  Principle:   142 (14%)
  Institution:  85 (9%)

Type × VSM coverage: 25/30 cells populated
  Missing: Institution/S1, Principle/S3*, Process/S5
```

### Layer 3: extract relations

```bash
# Extract relation triplets (per entity pair or per chapter):
markitect infospace extract-relations --provider openrouter

# View the relation graph:
markitect infospace graph --output output/relations/graph.dot

# Detect feedback loops:
markitect infospace loops
```

### Layer 4: distil the core

```bash
# Identify the minimal viable entity set:
markitect infospace distil --provider openrouter

# Review the core model:
cat output/core-model.md

# Check VSM completeness of the core:
markitect infospace viability --layer 4
```

---

## 23. Layer 2–4 as Composed Infospaces

The cleanest way to implement Layers 2–4 is as **separate infospaces**,
each using the previous layer as its topic and discipline. This is already
supported by the MarkiTect composition model.

```bash
# Layer 2 infospace — using L1 entities as the topic:
mkdir ../won-typed/
cd ../won-typed/
markitect infospace init \
  --topic "WoN Typed Entities" \
  --domain "Ontological Classification" \
  --discipline "Viable System Model"

# Bind the L1 infospace as the source topic:
markitect infospace bind-discipline ../infospace-with-history

# Layer 3 infospace — using L2 typed entities as the topic:
mkdir ../won-relations/
markitect infospace init \
  --topic "WoN Relation Graph" \
  --domain "Systemic Modelling"

markitect infospace bind-discipline ../won-typed

# Layer 4 infospace — the core model:
mkdir ../won-core/
markitect infospace init \
  --topic "WoN Core Model" \
  --domain "Systemic Modelling"

markitect infospace bind-discipline ../won-relations
```

This structure makes every distillation decision auditable through git
history. A reclassification in L2 (an entity's type changes from Process
to Relation) propagates as a flag on dependent L3 triplets, which in turn
flags the L4 core model for re-evaluation.

The intellectual history of how a theory was extracted from a text, typed,
connected, and distilled to its minimal core is fully preserved — as a set
of git commits, each with a human-readable rationale.