# Relation Triplet Schema — v1.0

Each file in `output/relations/` captures a single directed relation between
two entities from the L1 entity collection. Relations are the edges of the
L3 relation graph.

---

## Required Sections

### H1 — Relation title

Format: `# Subject — predicate phrase — Object`

Example: `# Division of Labour — limited by — Market Extent`

---

### Subject

The entity that is the **source** of the relation — the thing doing the
enabling, constraining, producing, etc.

Use the entity's exact title as it appears in its L1 entity file (H1 heading).

---

### Predicate

A short phrase from the **controlled relation vocabulary** (see below), or
a natural language variant that maps to one of those classes.

Examples: `limited by`, `enables`, `is regulated by`, `produces`

---

### Object

The entity that is the **target** of the relation — the thing being enabled,
constrained, regulated, etc.

Use the entity's exact title as it appears in its L1 entity file.

---

### Relation Type

The **semantic class** of the predicate, drawn from the controlled vocabulary:

| Relation Type | Meaning | Default VSM Channel |
|---|---|---|
| `enables` | Subject makes object possible or more effective | S1 → S1 |
| `constrains` | Subject limits or bounds the object | S1 ← S1 |
| `regulates` | Subject actively governs the object | S3 → S1 |
| `is regulated by` | Object governs the subject | S1 ← S3 |
| `coordinates` | Subject reduces oscillation or misalignment | S2 |
| `produces` | Subject generates the object as output | S1 |
| `consumes` | Subject depletes the object | S1 |
| `monitors` | Subject observes and reports on object | S3* |
| `audits` | Subject verifies compliance of object | S3* |
| `adapts to` | Subject adjusts in response to object | S4 |
| `anticipates` | Subject predicts or models the object | S4 |
| `defines` | Subject sets the identity or rules of object | S5 → any |
| `is defined by` | Object sets the identity or rules of subject | any ← S5 |
| `contradicts` | Subject is in direct logical conflict with object | any |
| `tensions with` | Subject and object exist in productive tension | any |

---

### VSM Channel

The Viable System Model systems involved in this relation, with direction.

Format: `S<n> → S<m>` or `S<n>` if the relation is within a single system.

Examples:
- `S1 → S2` — operation drives a coordination signal
- `S3 → S1` — management regulates operations
- `S2` — pure coordination within S2
- `S4 → S5` — intelligence informing policy

Use `S3*` for audit loops (Beer's algedonic channel).

---

### Evidence

Direct textual evidence from Adam Smith's text. Preferred format:

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

Use short quotes when available. Chapter reference alone is acceptable when
no single sentence captures the relation.

---

### Feedback Role (optional)

If this relation is part of a named feedback loop, describe its role here.
Name the loop and state what the relation contributes.

Example:
```
Part of the Market Expansion loop: larger market → more specialisation
→ higher productivity → greater surplus → expanded trade → larger market.
This edge (limited by) is the constraining link that turns the loop balancing
when market extent cannot grow further.
```

Omit or leave empty if the relation is not part of a known feedback loop.

---

## File Naming

Use the pattern: `<subject-slug>--<relation-type>--<object-slug>.md`

Where slugs are derived from entity titles using the same slugification as
entity files (lowercase, spaces and punctuation replaced with underscores).

Example: `division_of_labour--constrains--market_extent.md`

If two entities have the same relation type between them (unusual), append
a numeric suffix: `...-2.md`.

---

## Completeness Criteria

A relation file is **complete** if:
- All four required sections are present and non-empty
- The Relation Type is from the controlled vocabulary
- The VSM Channel is a valid VSM system designation
- Evidence references a specific Book and Chapter

A relation file is **acceptable** if:
- Required sections present but Evidence is missing (mark as `(unverified)`)
