markitect-main/docs/composition-guide.md

# Infospace Composition Guide

One completed, viable infospace can be reused as a **discipline** for
another infospace — a lens applied to a different topic. This guide
explains how composition works and walks through the live
`examples/supply-chain-vsm/` reference.

---

## What composition means

An **infospace** is a directory of typed entities governed by
`infospace.yaml`. Its entities and relations describe a specific topic
(for example, Adam Smith's *Wealth of Nations*).

A **discipline** is an infospace declared as a reusable analytical
framework by another infospace. When infospace B binds infospace A as a
discipline:

1. B's entities can reference A's entities in `## WoN Concept` (or
   equivalent) sections.
2. Properties A has already computed on its entities — such as VSM system
   placement — become available to B by transitivity through the mapping.
3. B can impose its own viability thresholds independently of A's. The two
   infospaces each pass or fail viability on their own terms.

The binding is declarative: a relative path in `infospace.yaml` plus a
display name. No code. No import. The discipline is looked up on disk at
the declared path when B's commands run.

---

## The viability pre-condition

Binding a non-viable infospace as a discipline is a mistake: a framework
that fails its own thresholds is not a stable reference frame. Before
binding, confirm the candidate discipline is viable:

```bash
cd examples/infospace-with-history
markitect infospace viability
```

```
Metric                            Value       Threshold   Status
---------------------------------------------------------------
redundancy_ratio                 0.0061         max=0.1     PASS
coverage_ratio                   0.6190         min=0.4     PASS
coherence_components             0.0000           max=3     PASS
consistency_cycles               0.0000           max=0     PASS
granularity_entropy              2.6748         min=1.0     PASS
per_entity_mean                  3.9556         min=3.5     PASS

Viable: YES (6/6 thresholds met)
```

If the discipline is not viable, fix it first (see
`examples/infospace-with-history/docs/advanced-usage.md` §4 for triaging
low scorers).

---

## Example — how `supply-chain-vsm` binds WoN

The supply-chain infospace declares WoN as a discipline in its
`infospace.yaml`:

```yaml
topic:
  name: "Modern Supply Chain Management"
  domain: "Operations Management"
  sources: artifacts/sources/

disciplines:
  - name: "Wealth of Nations"
    path: ../infospace-with-history
```

The binding is a **relative path**, so the two infospaces travel together
(they can be moved as a pair without breaking the link).

Verify the binding resolves and the discipline is viable:

```bash
cd examples/supply-chain-vsm
markitect infospace disciplines
```

```
Name                           Entities   Viable Path
----------------------------------------------------------------------
Wealth of Nations                   988      YES ../infospace-with-history
```

Each supply-chain entity then carries a `## WoN Concept` section
mapping it to exactly one WoN entity. The consolidated mapping files
(`output/mappings/*-mappings.md`) record the pairing, rationale, and a
conceptual-continuity rating (Strong / Moderate / Weak):

| Supply Chain Entity          | WoN Concept                      | Strength | VSM   |
|------------------------------|----------------------------------|----------|-------|
| Demand Signal                | Effectual Demand                 | Strong   | S2    |
| Vendor-Managed Inventory     | Division of Labour               | Strong   | S1/S2 |
| Just-in-Time Inventory       | Circulating Capital              | Strong   | S1/S3 |
| Bullwhip Effect              | Natural Price as Central Price   | Moderate | S2    |
| Safety Stock                 | Accumulation of Stock            | Moderate | S3    |

Because each WoN entity already has a VSM system placement (S1–S5), the
supply-chain entities inherit a VSM position by transitivity through
their mapping — without supply-chain-vsm needing its own VSM reference.

---

## Creating a new infospace that binds an existing one

Step-by-step, using WoN as the discipline for a hypothetical "Modern
Monetary Policy" infospace:

### 1. Start from the target topic

```bash
mkdir -p examples/monetary-policy/artifacts/sources
cd examples/monetary-policy
markitect infospace init
```

### 2. Declare the discipline in `infospace.yaml`

```yaml
topic:
  name: "Modern Monetary Policy"
  domain: "Macroeconomics"
  sources: artifacts/sources/

disciplines:
  - name: "Wealth of Nations"
    path: ../infospace-with-history
```

Alternatively, bind imperatively after `init`:

```bash
markitect infospace bind-discipline ../infospace-with-history --name "Wealth of Nations"
```

### 3. Set your own viability thresholds

Copy the `viability:` block from a reference infospace and tune the
numbers to the scale and maturity of your topic. A smaller infospace
(50 entities, not 988) may need laxer `coverage_ratio` and stricter
`redundancy_ratio`.

### 4. Verify the binding

```bash
markitect infospace disciplines
```

If `Viable` is `NO`, stop and fix the discipline before continuing.

### 5. Reference discipline entities in your own entities

For each entity in the new infospace, add a `## <Discipline> Concept`
section that names the WoN entity the concept maps to, plus a rationale.
The exact section heading is configured per schema — see
`schemas/won-mapping-schema-v1.0.md` in `supply-chain-vsm` for the
template used there.

### 6. Run checks and evaluate

```bash
markitect infospace check
markitect infospace evaluate --provider openrouter
markitect infospace eval-summary --update-metrics
markitect infospace viability
```

The new infospace passes or fails viability independently of WoN.

---

## Why composition, not inclusion?

An alternative would be to copy WoN entities directly into the target
infospace. Composition avoids that by design:

- **One source of truth** — if WoN is refined, every infospace that binds
  it picks up the improvement on the next run without a sync step.
- **Separation of concerns** — each infospace owns its own schema,
  thresholds, and entity set. Changing the target topic cannot pollute
  the discipline.
- **Bounded dependency** — the binding is a path, so the coupling is
  visible in one place (`infospace.yaml`) and easy to remove.

---

## See also

- `examples/supply-chain-vsm/README.md` — the full reference composition.
- `examples/supply-chain-vsm/output/mappings/` — consolidated mapping
  files showing the rationale and strength rating for each pairing.
- `examples/infospace-with-history/docs/advanced-usage.md` — patterns for
  maintaining the discipline once it is in use.