tegwick
36a5136bdf
Closes out three docs tasks from roadmap/infospace-s3-closeout/PLAN.md: - examples/infospace-with-history/docs/advanced-usage.md (C.4) — 5 worked patterns covering incremental eval, re-eval workflow (no --force flag exists; documents the rm-then-re-run pattern instead), interpreting the eval-summary distribution, triaging low scorers via an awk pipeline over overall_score (since `entities --sort-by score` does not exist), and acting on check --json output. - docs/composition-guide.md (C.5) — walks through how supply-chain-vsm binds WoN as a discipline, then a step-by-step for creating a new infospace that binds an existing one. Includes live output from `markitect infospace disciplines`. - examples/infospace-with-history/docs/performance-notes.md (C.6) — cites the 6h 28m wall time of the 985-entity S3.3 batch, ~2.5 ent/min rate, ~2000–3000 tokens/entity estimate, word_overlap vs embedding backend for redundancy checks, and a provider-by-scale recommendation table. All commands in these docs were run against the live infospace at commit time. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
204 lines
6.6 KiB
Markdown
204 lines
6.6 KiB
Markdown
# 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.
|