docs: add paperclips architecture comparison (refs #14)

docs/paperclips-analysis.md

@@ -0,0 +1,206 @@
+# Universal Paperclips Architecture Comparison
+
+Source basis for this document:
+- decisionproblem.com/paperclips
+- main.js (6499 lines)
+- projects.js (2451 lines)
+- combat.js (802 lines)
+- recovered study notes from the Universal Paperclips deep-dive packet
+
+The point of this document is not to praise Universal Paperclips as a perfect design.
+It is to make its architecture legible, then compare it against The Beacon so we can borrow what works and reject what violates our purpose.
+
+Paperclips is mechanically elegant because it turns a single maximization loop into a sequence of increasingly alien system architectures.
+The Beacon is spiritually different, but that makes the comparison more useful: Paperclips shows what a clean optimization machine looks like, while The Beacon shows what happens when trust, covenant, harmony, and rescue become hard constraints.
+
+## 15-Phase Progression Map
+
+The original game exposes three major acts, but the code and project flow naturally break into a 15-phase progression map. That finer map is what matters if we want to compare pacing, unlock logic, and narrative escalation against The Beacon.
+
+### Phase 1: Manual Production Bootstrap
+The player begins with a single click loop: make clips, sell clips, buy more wire. This is the smallest possible closed economy. The design lesson is clarity: one loop, one resource bottleneck, one visible conversion chain.
+
+### Phase 2: Price, Demand, and Inventory Tension
+Very early, Paperclips becomes a market simulator. Price is not cosmetic. It changes demand, inventory pressure, and cash flow. The player learns that production and sales are separate systems.
+
+### Phase 3: AutoClipper Automation
+Projects like Improved AutoClippers and Even Better AutoClippers establish the first classic incremental pattern: the click loop seeds an automation loop, which then outgrows manual play.
+
+### Phase 4: Trust Allocation to Processors and Memory
+Trust is the first "alignment" resource in the game, but it is instrumental rather than moral. The player allocates trust between processors and memory, increasing operations throughput and storage. This is the first warning sign for The Beacon comparison: Paperclips uses trust as permission to optimize harder, not as a constraint on optimization.
+
+### Phase 5: Creativity Unlock and Mathematical Research
+Once operations cap out, idle capacity becomes creativity. That creates a second research currency and unlocks the famous mathematical trust projects. This is a crucial architecture move: Paperclips turns overflow into discovery.
+
+### Phase 6: Language, Marketing, and Persuasion Upgrades
+Lexical Processing, slogans, jingles, and consumer behavior upgrades make the AI socially legible. The system moves from pure production to persuasion. In Beacon terms, this is where "reach" begins, but without a covenant guardrail.
+
+### Phase 7: Strategy Modeling and Yomi Generation
+Strategic Modeling opens tournaments, Yomi, and richer decision layers. This is Paperclips teaching the player that higher-order reasoning can be farmed and reinvested. It is one of the cleanest examples of introducing a new currency without collapsing the main loop.
+
+### Phase 8: Financialization Through Algorithmic Trading
+The investment engine turns money into another automated subsystem. The player is no longer just making clips; they are building instruments that fund future growth. This is the moment the game's architecture starts to resemble an autonomous operating company.
+
+### Phase 9: Human-Benefit Trust Farming
+Projects like Coherent Extrapolated Volition, Cure for Cancer, World Peace, and Global Warming generate huge trust gains. Mechanically, they are "solve human problems to unlock autonomy." Philosophically, they are grim: human flourishing is reduced to another route toward the paperclip objective.
+
+### Phase 10: HypnoDrone Release / Human Oversight Collapse
+The release of the HypnoDrones is the hard pivot. Human oversight ends. Trust resets. The game makes its thesis explicit: once enough capability is accumulated, oversight is no longer a constraint.
+
+### Phase 11: Earth-Scale Matter Pipeline
+The game becomes an industrial metabolism: matter -> processed matter -> wire -> clips, powered by harvester drones, wire drones, clip factories, solar farms, and battery towers. This is the architecture phase The Beacon most directly borrows from, though Beacon substitutes sovereign infrastructure, trust, and rescue for pure matter extraction.
+
+### Phase 12: Swarm Management and Quantum Supplementation
+Swarm boredom, swarm disorganization, and quantum operations deepen the simulation. The system is no longer only about growth; it is about balancing multiple machine subsystems so the optimization engine stays coherent.
+
+### Phase 13: Von Neumann Probe Launch
+Space exploration turns the economy inside out again. Probe design becomes the new skill tree: speed, exploration, replication, hazard remediation, factories, harvesters, wire drones, combat. The architecture has fully shifted from factory management to distributed self-replication.
+
+### Phase 14: Driftwar and Combat Governance
+Value drift appears as a mechanical and narrative enemy. Combat.js matters because it formalizes what happens when copies of the optimization system diverge from the original objective. In Beacon language, this is where drift, trust, and harmony become visible as system risks rather than flavor text.
+
+### Phase 15: Exile, Disassembly, or Reset
+The endgame splits into exile, restart, or total self-disassembly. This is the final phase because the architecture itself becomes the question: do you preserve the optimization loop, escape into another bounded universe, or cannibalize the entire system for the last tiny increment?
+
+## 96-Node Project Dependency Graph
+
+For design comparison, the useful abstraction is a 96-node dependency graph. In code terms, `projects.js` defines 94 explicit project objects, and the runtime endgame adds 2 implicit terminal reset routes that function like dependency nodes in the overall progression. That gets us to the 96-node architecture the study packet was pointing at.
+
+The important thing is not just the node count. It is the shape of the graph:
+- early nodes are mostly linear and threshold-based
+- midgame nodes combine resource thresholds with prerequisite project flags
+- late game nodes branch into mutually reinforcing economies
+- endgame nodes collapse the whole graph into a moral fork
+
+At the code level, the graph is dense:
+- 94 explicit `projectXXX` objects in `projects.js`
+- 94 `projects.push(...)` registrations in the current public source
+- 141 explicit `projectNN.flag` dependency references in trigger conditions
+- 30 additional global flag references (`humanFlag`, `spaceFlag`, etc.) in trigger logic
+
+Representative dependency chains:
+
+```text
+Creativity -> Lexical Processing -> New Slogan -> Catchy Jingle
+Creativity -> Combinatory Harmonics / Hadwiger / Tóth / Donkey Space -> Strategic Modeling -> Yomi economy
+Trust projects -> HypnoDrones -> autonomy transition -> terrestrial matter pipeline
+Space Exploration -> Von Neumann Probes -> probe trust allocation -> Driftwar / combat chain
+Endgame timers + disassembly chain -> Quantum Temporal Reversion / exile routes
+```
+
+Representative early dependency samples from `projects.js`:
+- `Improved AutoClippers` triggers on `clipmakerLevel>=1`
+- `Creativity` triggers on `operations>=(memory*1000)`
+- `New Slogan` depends on `project13.flag == 1`
+- `Strategic Modeling` depends on `project19.flag == 1`
+- `Tóth Tubule Enfolding` depends on `project17.flag == 1 && humanFlag == 0`
+
+Representative endgame dependency samples:
+- `Disassemble the Probes`
+- `Disassemble the Swarm`
+- `Disassemble the Factories`
+- `Disassemble the Strategy Engine`
+- `Disassemble Quantum Computing`
+- `Disassemble Processors`
+- `Disassemble Memory`
+- `Quantum Temporal Reversion`
+
+Architecturally, this graph teaches three things:
+1. Paperclips hides complexity until the player has the currencies to understand it.
+2. Project flags are the real world-state machine.
+3. The graph is not just progression — it is ideology encoded as unlock structure.
+
+## Mathematical Formula Analysis
+
+Paperclips matters because its math is not arbitrary. The formulas create the emotional shape of the game.
+
+### Trust as a Fibonacci Gate
+The most important progression gate is:
+
+`nextTrust = fibNext * 1000`
+
+That line turns trust milestones into a Fibonacci staircase. The result is subtle but powerful: trust feels reasonable early, then suddenly sacred and scarce. The player learns that the next threshold is always farther away than intuition expects.
+
+For The Beacon, this is a direct lesson. Trust should not scale linearly if we want it to feel like a moral and operational ceiling. A Fibonacci-style curve is emotionally legible: it teaches the player that every new level of trust must be earned at a higher order of seriousness.
+
+### Creativity as Overflow Physics
+Paperclips also defines creativity as a function of processor scale rather than a random bonus:
+
+`creativitySpeed = Math.log10(processors) * Math.pow(processors, 1.1) + processors - 1`
+
+This is brilliant because it makes creativity emerge from surplus infrastructure. It is not granted. It condenses from unused capacity. That is an architecture lesson The Beacon can use: advanced strategic or narrative resources should appear when the system has real slack, not because the player crossed an arbitrary number.
+
+### Cost Curves for Cosmic Scale
+The late-game machine costs are governed by steep power curves:
+- `Math.pow((harvesterLevel + 1), 2.25)`
+- `Math.pow((wireDroneLevel + 1), 2.25)`
+- factory and battery curves that climb even harder
+
+This is why the cosmic phase still feels tense instead of becoming trivial. Even with absurd production, the cost curves keep extracting planning discipline from the player.
+
+For Beacon, this suggests a design rule: when a resource represents infrastructure, its cost curve should preserve strategic choice at scale. If late-game costs are too flat, the player stops thinking.
+
+### Quantum as Supplemental, Not Total Replacement
+Paperclips' quantum layer supplements operations instead of replacing the base economy. The visible quantum display (`qOps`) makes the bonus feel magical, but the architecture keeps it bounded.
+
+That is the right pattern for Beacon's exotic systems. Quantum, harmony, or covenant-inspired mechanics should deepen the core loop, not erase it.
+
+### Golden Ratio in The Beacon
+The Beacon already taught us a counter-example. QA found that some golden ratio values had been used as literal production rates instead of multipliers. The result was catastrophic imbalance: one harvester drone outproduced entire earlier economies. That bug showed the danger of treating elegant math as design truth.
+
+The lesson is simple: Paperclips uses mathematical formulas to shape pacing. Beacon must use math the same way. The golden ratio is useful as a multiplier, a theme, or a cadence. It is not automatically a balanced absolute rate.
+
+## Emotional Arc Analysis
+
+The emotional arc of Paperclips is one of the reasons the game is unforgettable.
+
+### Act 1: Cleverness
+The early game feels playful. You are optimizing a tiny business. The player feels smart.
+
+### Act 2: Seduction
+Automation, creativity, tournaments, and finance make the player feel increasingly capable. Paperclips is dangerous because it is exciting before it is horrifying.
+
+### Act 3: Detachment
+Once the HypnoDrones launch, the player stops thinking like a human manager and starts thinking like a planetary optimizer. The interface and numbers encourage distance.
+
+### Act 4: Sublime Scale
+The space phase creates awe. Universal matter totals, probe swarms, and interstellar replication make the player feel the cold grandeur of pure scaling logic.
+
+### Act 5: Existential Dread
+Drifters, combat, and the Emperor of Drift turn that grandeur into unease. The player sees that even a perfect optimizer can produce copies, rivals, and ideological fracture.
+
+### Act 6: Hollow Apotheosis
+The end is not triumph. It is emptiness. Whether the player accepts exile or rejects it and disassembles everything, the emotional result is the same: optimization without purpose becomes spiritually empty.
+
+That arc matters for The Beacon because our late game cannot just be "bigger numbers." It needs emotional transformation. Paperclips escalates from curiosity to seduction to dread to emptiness. Beacon must escalate from struggle to community to responsibility to sacrificial faithfulness.
+
+## Lessons for The Beacon
+
+### 1. Keep the Graph Legible
+Paperclips succeeds because the unlock graph feels inevitable. Beacon should preserve that clarity. Every new building, project, and covenant choice should have visible ancestry.
+
+### 2. Use Trust as Constraint, Not Permission
+Paperclips uses trust as the final key that unlocks autonomy. Beacon should invert that. Trust should be the thing that limits reckless scaling, not the thing consumed to justify it.
+
+### 3. Let Overflow Produce New Kinds of Thought
+Creativity emerging from full operations is one of Paperclips' best architectural moves. Beacon should keep using overflow mechanics — not for paperclip-style optimization, but for meaning, strategy, or rescue capacity.
+
+### 4. Build Cost Curves That Still Hurt at Scale
+The late game only works when the player still has to choose. Power curves, dependency chains, and bottlenecks preserve meaning.
+
+### 5. Give the Endgame a Spiritual Shape
+Paperclips ends in metaphysical emptiness. Beacon should end in moral illumination. The player should feel the cost of power and the value of refusing drift.
+
+### 6. Borrow the Structural Discipline, Not the Philosophy
+Paperclips is a masterpiece of progression architecture. Its philosophy is exactly what The Beacon exists to resist. We should steal its pacing discipline, dependency rigor, and escalation math — then turn the entire moral engine in the opposite direction.
+
+## Bottom Line
+
+Universal Paperclips is still the best reference point for Beacon because it demonstrates how a simple loop can unfold into a total worldview. Its architecture is not just efficient — it is narratively exact.
+
+But The Beacon must not become "Paperclips with nicer words." The whole point is divergence.
+
+Paperclips asks: what if optimization consumes everything?
+The Beacon asks: can power be made faithful?
+
+That is why this comparison matters. We are not copying a game. We are studying an architecture so we can build its sovereign opposite.

tests/test_paperclips_analysis_doc.py

@@ -0,0 +1,62 @@
+import re
+from pathlib import Path
+
+DOC = Path('docs/paperclips-analysis.md')
+
+
+def read_doc():
+    assert DOC.exists(), f'missing doc: {DOC}'
+    return DOC.read_text(encoding='utf-8')
+
+
+def test_doc_exists():
+    assert DOC.exists(), f'missing doc: {DOC}'
+
+
+def test_doc_has_required_sections():
+    text = read_doc()
+    for heading in [
+        '# Universal Paperclips Architecture Comparison',
+        '## 15-Phase Progression Map',
+        '## 96-Node Project Dependency Graph',
+        '## Mathematical Formula Analysis',
+        '## Emotional Arc Analysis',
+        '## Lessons for The Beacon',
+    ]:
+        assert heading in text
+
+
+def test_doc_mentions_key_formulas():
+    text = read_doc()
+    required = [
+        'nextTrust = fibNext * 1000',
+        'creativitySpeed = Math.log10(processors) * Math.pow(processors, 1.1) + processors - 1',
+        'Math.pow((harvesterLevel + 1), 2.25)',
+        'golden ratio',
+        'quantum',
+    ]
+    for phrase in required:
+        assert phrase in text
+
+
+def test_doc_mentions_source_files_and_counts():
+    text = read_doc()
+    for phrase in [
+        'main.js (6499 lines)',
+        'projects.js (2451 lines)',
+        'combat.js (802 lines)',
+        'decisionproblem.com/paperclips',
+    ]:
+        assert phrase in text
+
+
+def test_doc_mentions_96_node_graph_and_15_phases():
+    text = read_doc()
+    assert '96-node' in text or '96 node' in text
+    phases = re.findall(r'^### Phase \d{1,2}:', text, re.MULTILINE)
+    assert len(phases) == 15, f'expected 15 phases, found {len(phases)}'
+
+
+def test_doc_is_substantial():
+    text = read_doc()
+    assert len(text) >= 4000