coulomb/markitect-main
2
0
Fork 0
Code Issues 60 Pull Requests Actions Projects 12 Releases 1 Wiki Activity

feat(example): add supply-chain-vsm composition demo (S3.5)

Browse Source 
Demonstrates infospace composition: the Wealth of Nations infospace is
used as a discipline, applying Smith's economic framework as a lens to
analyse modern supply chain management concepts.

New example: examples/supply-chain-vsm/
- infospace.yaml binding WoN as discipline (../infospace-with-history)
- 3 source documents: coordination mechanisms, capital & inventory,
  market structure (~400 words each, original content)
- supply-chain-entity-schema-v1.0.md with WoN Concept required section
- won-mapping-schema-v1.0.md with Conceptual Continuity rating
- artifacts/won-reference/core-entities.md — 12 curated WoN entities
  for injection as discipline context
- 8 hand-crafted entity files demonstrating LLM output format
- 3 mapping files with full rationale and VSM inheritance chains
- Viable: YES (5/5 thresholds)

Key mappings demonstrated:
  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           (Moderate, S2)
  Platform Intermediary  → Merchant Capital        (Strong, S2/S4)
  Monopsony Power        → Combination of Masters  (Strong, S3*)

Platform fix: entity_parser.py now recognises ## Supply Chain Domain
as a domain alias for ## Economic Domain, enabling composed infospaces
to use their own domain section name.

Tutorial §13 rewritten with real commands, real output, and the full
mapping table from the demo.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Bernd Worsch
2026-02-23 00:08:51 +01:00
parent 8f00fa2018
commit 574bb11db6
27 changed files with 1696 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files

50
examples/supply-chain-vsm/artifacts/guidelines/extraction-rules.md Normal file
View File

@@ -0,0 +1,50 @@
# Entity Extraction Rules — Supply Chain Infospace
## What Constitutes an Entity
Extract a concept as an entity when it is:
1. **Named**: referred to by a consistent, recognisable label in the
source material
2. **Distinct**: meaningfully different from other entities being extracted
3. **Explanatory**: contributes to understanding how supply chains work,
fail, or could be improved
4. **Mappable**: has a plausible correspondence to at least one concept in
the Wealth of Nations reference set
Do NOT extract:
- Proper nouns for specific companies or products (Toyota, Amazon) unless
they name a concept (e.g., the Toyota Production System is a concept)
- Historical examples unless the example itself is the concept
- Vague modifiers (e.g., "lean", "agile" as standalone adjectives)
## Granularity Rules
Target 4–8 entities per source document. Avoid:
- Entities so broad they subsume multiple distinct mechanisms (split them)
- Entities so narrow they are examples of a broader concept (elevate them)
- Entities that restate the same concept with different words (merge them)
## Naming Conventions
- Title case: `Bullwhip Effect`, not `bullwhip effect`
- Noun phrases: `Supply Chain Visibility`, not `supply chain is visible`
- Avoid acronyms in titles: `Just-in-Time Inventory`, not `JIT Inventory`
## WoN Cross-Reference
For each entity, consult the WoN core entity reference
(`artifacts/won-reference/core-entities.md`) to identify the most relevant
Wealth of Nations concept. Every entity should have a WoN Concept section —
even if the mapping is weak, noting the absence of a direct analogue is
informative.
## Supply Chain Domain Assignment
Assign the supply chain domain that best characterises the entity:
- **Coordination**: mechanisms that synchronise activity across chain nodes
- **Capital Management**: decisions about how working capital is deployed
- **Market Structure**: competitive arrangements, power relations, platform dynamics
- **Risk**: disruption, fragility, resilience
- **Logistics**: physical movement, warehousing, last-mile

60
examples/supply-chain-vsm/artifacts/guidelines/mapping-rules.md Normal file
View File

@@ -0,0 +1,60 @@
# WoN Mapping Rules — Supply Chain Infospace
## Purpose of Mapping
The mapping stage asks: which Wealth of Nations concept does this supply
chain entity most directly correspond to? The goal is not to find a
superficial name match but to identify structural correspondence — same
mechanism, same trade-off, same systemic role — even when the surface form
is entirely different.
Smith had no concept of just-in-time inventory or logistics platforms. But
he had detailed accounts of circulating capital, merchant intermediaries,
and market price oscillation. The mapping discipline asks whether modern
concepts are genuinely new structures or modern instantiations of mechanisms
Smith already described.
## Mapping Strength Calibration
**Strong**: The modern concept and the WoN concept are the same mechanism
in different historical settings. The supply chain entity could be used
as an example in a modern edition of Smith's chapter, with only contextual
updating needed.
Example: Vendor-Managed Inventory is a Strong map to Division of Labour —
the function of inventory management is delegated to the party with the
greatest competence and information, which is precisely Smith's argument
for specialisation.
**Moderate**: The concepts share structural logic but differ in important
ways — the modern concept has features Smith's lacks, or operates under
conditions Smith did not analyse. The WoN concept illuminates the modern
concept but does not fully characterise it.
Example: Bullwhip Effect is a Moderate map to Natural Price as Central Price —
both describe oscillation of a market signal around a theoretical equilibrium,
but the bullwhip's amplification mechanism is an information distortion Smith
did not analyse in this form.
**Weak**: The mapping is analogical — useful for analysis but the
correspondence is partial or strained. The WoN concept provides a useful
frame but should not be treated as explanatory of the modern concept.
## One-to-Many Mappings
A supply chain entity may map to more than one WoN concept. Where this
occurs, create a separate mapping entry for each WoN concept, explaining
the different facets each illuminates.
## Unmappable Entities
If no plausible WoN mapping exists (the concept is genuinely novel),
document this explicitly with a brief explanation of what Smith's framework
lacks that would be needed to capture the concept.
## VSM Inheritance
Every WoN entity in the reference set has a VSM system assignment. When
a supply chain entity maps to a WoN entity, it inherits that VSM position.
If the supply chain entity maps to multiple WoN entities with different VSM
assignments, note the primary inheritance and explain any secondary VSM roles.

69
examples/supply-chain-vsm/artifacts/sources/capital-and-inventory.md Normal file
View File

@@ -0,0 +1,69 @@
# Capital and Inventory in Supply Chain Management
## Inventory as Frozen Capital
Inventory is working capital immobilised in physical form. Every unit of
stock sitting in a warehouse represents capital that has been deployed but
not yet returned. The cash-to-cash cycle — the time between paying a
supplier and receiving payment from a customer — determines how much
working capital a business must hold at any moment. A long cycle requires
more capital; a short cycle requires less.
This relationship makes inventory management inseparable from capital
management. Decisions about how much stock to hold, where to hold it, and
in what form are simultaneously decisions about how to deploy scarce capital.
Excess inventory does not merely incur storage costs; it has an opportunity
cost equal to the return that capital could earn in its next best use.
## Just-in-Time Inventory
Just-in-time (JIT) inventory management is the practice of receiving goods
from suppliers only as they are needed in the production process or for
customer fulfilment, thereby minimising the volume of inventory held at any
moment. JIT was developed in the Japanese automotive industry and achieved
its most influential form at Toyota, where it became part of the Toyota
Production System.
The goal of JIT is to eliminate inventory as a buffer. Where traditional
manufacturing used inventory to absorb variability in supply and demand,
JIT addresses variability directly — through reliable supplier relationships,
short production runs, and rapid changeover. The capital released from
inventory reduction is the primary financial justification for the
substantial coordination investments JIT requires.
JIT succeeds when supply chains are stable, geographically concentrated,
and have high-quality supplier relationships. It fails when exposed to
supply shocks, as the 2011 Tōhoku earthquake and the 2020–2022 global
supply chain disruptions demonstrated: the same lean buffers that minimise
capital in stable conditions amplify vulnerability in unstable ones.
## Safety Stock and Reserve Capacity
Safety stock is inventory held in excess of expected demand to buffer
against uncertainty. It is a form of capital deliberately kept unproductive
in order to preserve operational continuity. The optimal safety stock level
balances the cost of holding excess inventory against the cost of stockouts —
lost sales, production stoppages, and damaged customer relationships.
The existence of safety stock reflects a fundamental trade-off in supply
chain design: capital efficiency versus operational resilience. A supply
chain optimised purely for capital efficiency holds no safety stock, but
collapses at the first supply disruption. A supply chain optimised for
resilience holds substantial safety stock, but earns a low return on
capital employed.
## Working Capital Optimisation
Working capital optimisation is the systematic management of the
cash-to-cash cycle to reduce the amount of capital tied up in operations
at any point. The primary levers are: reducing inventory levels (JIT, VMI),
shortening the receivables cycle (faster collection from customers), and
lengthening the payables cycle (slower payment to suppliers).
Large buyers — particularly major retailers and platform companies — use
their market power to extend payment terms to suppliers to 60, 90, or 120
days while collecting from customers within days. This transfers the
financing burden of working capital to the supply chain without reducing
the buyer's operational requirements. The result is an effective subsidy
from suppliers (often smaller and more capital-constrained) to buyers
(typically larger and better-capitalised).

63
examples/supply-chain-vsm/artifacts/sources/coordination-mechanisms.md Normal file
View File

@@ -0,0 +1,63 @@
# Coordination Mechanisms in Modern Supply Chains
## Demand Signals and Information Flow
Supply chains coordinate through the propagation of demand signals upstream
from end consumers through retailers, distributors, and manufacturers to raw
material suppliers. The quality and latency of these signals determine how
well production is synchronised with actual consumption.
In a well-functioning supply chain, a retailer's point-of-sale data becomes
the input signal for a distributor's replenishment order, which in turn
signals the manufacturer to schedule production runs. When this chain
operates with full transparency and zero delay, production closely tracks
consumption. When it operates with delays, batching, or information
filtering, coordination failures emerge.
## The Bullwhip Effect
The bullwhip effect describes the amplification of demand variability as
signals travel upstream in a supply chain. A 5% fluctuation in retail
demand may translate into a 20% fluctuation in distributor orders and a
40% swing in manufacturer production schedules. This amplification occurs
because each node in the chain adds a safety buffer to its orders, reacts
to the previous period's signal rather than real-time data, and places
orders in discrete batches rather than continuously.
The result is a supply chain that oscillates — periods of excess inventory
alternating with periods of shortage — even when underlying consumer demand
is relatively stable. The bullwhip effect is not a market equilibrium; it
is a coordination failure in which the absence of shared real-time
information causes each rational local decision to produce irrational
aggregate outcomes.
## Vendor-Managed Inventory
Vendor-managed inventory (VMI) is a coordination arrangement in which the
supplier, rather than the buyer, is responsible for maintaining stock levels
at the buyer's location. The supplier has read access to the buyer's
inventory data and automatically replenishes when stock falls below a
specified threshold. Payment occurs when the buyer consumes the goods, not
when they arrive.
VMI represents a reallocation of the inventory management function: the
buyer surrenders operational control over a specific task (replenishment)
to the party better positioned to perform it (the supplier, who controls
the supply side). This specialisation of function reduces transaction costs,
improves forecast accuracy (the supplier sees real consumption, not
batch orders), and smooths the demand signal upstream.
## Supply Chain Visibility
Supply chain visibility refers to the degree to which all participants can
observe the state of inventory, orders, and shipments across the entire
chain in real time. High visibility reduces the information asymmetries
that drive the bullwhip effect and enables coordinated responses to
disruption.
Modern visibility platforms aggregate data from tracking systems, IoT
sensors, and partner APIs to provide a unified operational picture. The
commercial value of visibility comes from reducing the cost of safety
stock (since uncertainty is lower) and enabling faster responses to supply
shocks. Visibility is not merely a technical feature; it is a coordination
mechanism that changes the incentive structure for every node in the chain.

71
examples/supply-chain-vsm/artifacts/sources/market-structure.md Normal file
View File

@@ -0,0 +1,71 @@
# Market Structure in Modern Supply Chains
## Platform Intermediaries
A platform intermediary in a supply chain context is a company that does
not itself produce or consume goods but instead controls the infrastructure
through which buyers and sellers transact. Platform intermediaries include
e-commerce marketplaces (Amazon, Alibaba), logistics platforms (Flexport,
FreightOS), and procurement networks (Coupa, Ariba). Their value lies not
in physical capital but in network effects: the platform becomes more
valuable to each participant as the total number of participants grows.
Platform intermediaries extract value by charging transaction fees, selling
data analytics, providing financing, or leveraging their position to capture
margin that previously accrued to producers or carriers. Their market power
derives from control of the matching infrastructure: a seller who abandons
the platform loses access to the buyer network; a buyer who abandons the
platform loses access to the supplier network.
Unlike traditional merchant intermediaries — who bought and sold goods,
bearing inventory risk — platform intermediaries transfer inventory risk to
the counterparties. The platform earns commission on each transaction but
holds no stock; the asymmetry concentrates profit in the intermediary while
concentrating risk in producers and carriers.
## Monopsony and Buyer Power
Monopsony is market power on the buyer's side: a situation in which a
single buyer (or a small number of buyers acting in concert) faces many
sellers. In supply chains, monopsony manifests when a large retailer or
manufacturer is the dominant customer for a category of suppliers. The
buyer's ability to credibly threaten to switch suppliers — or to reduce
purchase volumes — gives it negotiating leverage that suppliers cannot
easily counter.
Buyer power is exercised through price pressure (demanding lower unit costs
in each contract renegotiation), terms pressure (extending payment terms,
imposing fines for delivery failures), and specification creep (adding
requirements without cost compensation). Suppliers facing strong buyer power
are systematically squeezed: their margins decline, their ability to invest
in quality and capacity is constrained, and their bargaining position
deteriorates further as the buyer grows.
The long-run consequence of sustained monopsony pressure is supplier
consolidation — weaker suppliers exit, leaving the buyer with fewer but
larger suppliers — and supply fragility, as the surviving suppliers have
insufficient margin to hold safety stock or invest in resilience.
## Market Concentration and Single-Source Dependencies
Single-source dependency occurs when a supply chain relies on one supplier
for a critical component or material with no readily substitutable
alternative. Single-source situations arise from supplier specialisation
(only one firm has the required capability), geographic concentration (all
competent suppliers are in one region), or deliberate buyer policy (choosing
the best supplier and extracting maximum scale economies).
Single-source dependencies concentrate supply chain risk. When a
single-sourced supplier fails — due to fire, flood, earthquake, insolvency,
or geopolitical disruption — the buyer has no immediate alternative. The
semiconductor industry exemplifies this: certain advanced logic chips can
only be produced by one or two foundries globally, making entire sectors
of the world economy dependent on the operational continuity of a small
number of facilities in Taiwan and South Korea.
From a market structure perspective, single-source suppliers possess
temporary monopoly power: during a supply disruption, they can charge
prices far above their normal level, because no substitute exists. Smith's
analysis of monopoly price — that it is the highest that can be squeezed
from buyers — applies directly: a disrupted single-source supplier in a
critical category faces demand that is inelastic in the short run.

192
examples/supply-chain-vsm/artifacts/won-reference/core-entities.md Normal file
View File

@@ -0,0 +1,192 @@
# Wealth of Nations — Core Entities Reference
A curated selection of WoN entities from the infospace at
`../infospace-with-history/output/entities/`, chosen for their relevance
to supply chain analysis. Use these as mapping targets in the
`map-to-won` pipeline stage.
---
## Division of Labour
Slug: `division-of-labour`
The specialisation of tasks among workers or firms, each focusing on a
narrow function to increase overall productive efficiency. Smith argues
this is the primary source of economic progress, enabled by the certainty
that surplus production can be exchanged.
VSM: S1 (primary operational mechanism)
---
## Effectual Demand
Slug: `effectual-demand`
The demand of those who are willing and able to pay the natural price of
a commodity. Effectual demand, not total desire, is what calls productive
resources into action. When effectual demand exceeds supply, market price
rises above natural price; when it falls short, market price falls below.
VSM: S2 (coordination signal — regulates resource allocation)
---
## Natural Price as Central Price
Slug: `natural-price-as-central-price`
The natural price is the centre around which market prices continually
gravitate. When the market price exceeds the natural price, capital is
attracted; when it falls below, capital exits. The natural price is thus
an equilibrium attractor that Smith likens to a centre of gravity.
VSM: S2 (coordination signal — equilibrium reference point)
---
## Market Price Adjustment Mechanism
Slug: `market-price-adjustment-mechanism`
The process by which market price moves toward natural price through
changes in supply. Excess supply depresses market price; scarcity raises
it. The mechanism depends on capital mobility: if capital can freely enter
and exit a sector, prices will converge to natural levels. Restrictions on
capital mobility (monopoly, regulation) prevent convergence.
VSM: S2 (coordination mechanism — negative feedback loop)
---
## Circulating Capital
Slug: `circulating-capital`
The component of capital that is used up in the course of a single
productive cycle and must be continually replaced. Includes raw materials,
work-in-progress, and the wages fund. Distinguished from fixed capital
(machinery, buildings) by the fact that it yields its return only by
changing hands. The speed of circulation determines how productively
a given capital stock can be employed.
VSM: S1 / S3 (operational resource; managed for return velocity)
---
## Accumulation of Stock
Slug: `accumulation-of-stock`
The process of building up capital reserves from savings (frugality),
enabling future investment in productive capacity. Smith argues that
capital accumulation precedes and enables division of labour — you cannot
specialise workers until you have stock to sustain them while production
is in progress. Stock functions as a buffer between production and
consumption.
VSM: S3 (capital management — enables S1 operations)
---
## Merchant Capital
Slug: `merchant-capital`
Capital employed by merchants who buy goods in one market and sell them in
another, earning a profit from price differentials without directly engaging
in production. Merchant capital performs the function of distribution:
connecting producers and consumers who would otherwise face prohibitive
search and transaction costs. Smith notes that merchants are mobile — they
have no necessary attachment to any particular country — and that this
mobility gives them leverage over producers and governments.
VSM: S2 / S4 (coordination; also market intelligence function)
---
## Monopoly in Trade
Slug: `monopoly-in-trade`
A situation in which a single seller or a privileged group of sellers
control supply in a market, enabling them to set prices above the natural
level. Smith argues monopoly prices are always the highest that can be
extracted from buyers, whereas competition drives prices toward the
natural level. Monopoly distorts resource allocation by keeping prices
high and restricting supply below what free competition would provide.
VSM: S5 (policy distortion — violates S2 equilibrating function)
---
## Combination of Masters
Slug: `combination-of-masters`
The coordinated action by employers to restrain wages or otherwise
improve their negotiating position relative to workers. Smith observes
that such combinations are common but rarely discussed publicly. The
practical effect is monopsony-like suppression of the returns to labour
below their natural level.
VSM: S3* (audit / anti-competitive practice — distorts S2 signals)
---
## Higgling and Bargaining of the Market
Slug: `higgling-and-bargaining-of-the-market`
The process of price discovery through negotiation between buyers and
sellers. Smith describes it as the mechanism by which value in exchange
is determined in practice — not by abstract calculation but by the
push-and-pull of each party pursuing their own interest, with the result
tending toward a price both can accept.
VSM: S2 (real-time coordination mechanism)
---
## Invisible Hand Mechanism
Slug: `invisible-hand-mechanism`
The process by which individuals pursuing their private economic interest
unintentionally produce outcomes beneficial to the whole economy. Smith
uses this metaphor specifically for domestic investment decisions: a
merchant who prefers domestic to foreign investment for security reasons
inadvertently maximises domestic productive capacity. The mechanism does
not require coordination — it is an emergent property of distributed
self-interested action under competitive conditions.
VSM: S4 (distributed intelligence — environmental adaptation without
central direction)
---
## Capital Security Preference
Slug: `capital-security-preference`
Smith's observation that capital owners systematically prefer less risky
applications of their capital over more risky ones, even when the expected
return might favour the riskier option. This preference shapes the
allocation of capital across sectors and geographic areas.
VSM: S3 (capital management — explains capital allocation patterns)
---
## Market Communication Channels
Slug: `market-communication-channels`
The mechanisms through which information about prices, quantities, and
conditions flows between market participants. Smith implicitly relies on
such channels for his account of price adjustment — if buyers and sellers
cannot learn each other's prices and terms, the equilibrating mechanism
breaks down.
VSM: S2 (information infrastructure for coordination)