# yysworld > One being. Multiple timelines. All traceable. yysworld is a branching life observatory. A single fictional character (YY, a squirrel) lives through real-world events, but under controlled variation — different starting states, different circumstances, different accumulated burdens. The divergence between paths is the product. --- ## What this is A provenance-preserving, versioned, branching narrative system where: - The same real-world event reaches every timeline simultaneously - Each branch experiences it differently based on accumulated state (food, health, attention, burdens) - Every artifact, decision, and divergence is publicly traceable - Human authority is absolute — AI assists, generates, and proposes; it does not define canon ## What this is not - Not a game — YY is observed, not played - Not a prediction system — branches show divergence, not forecasts - Not child-directed — family-shareable, adult-facing - Not a simulation of the real world — events are real-world anchored but abstracted to be universal - Not AI-generated canon — the author selects events, approves all artifacts, controls branching --- ## The ontology This system has five levels of hierarchy: Character — the canonical entity (YY, a squirrel) └── Run — a bounded arc, usually one month, starting from a shared baseline └── Branch — a divergent path, created when a mutation event occurs └── Day — one published story day; one event, one artifact per branch └── Event — a real-world anchor translated into YY's physical world A single real-world event applies to all branches simultaneously. The branches diverge in how they experience it, based on their accumulated state. The comparison between branches on the same day is a core product surface. Key state variables per branch: food (0–1), health (0–1), attention (0–1), active_burdens (list) --- ## URL structure ### Human-facing pages /yy/ → character page (runs index) /yy/about/ → character profile, traits, values /yy/{runDate}/{branch}/day/{N}/ → day artifact (story + state delta) /yy/{runDate}/vs/{branchA}/{branchB}/day/{N}/ → branch comparison for that day /adrs/ → architecture decision index /adrs/{slug}/ → single ADR ### Machine-facing data /yy/data/{YYYY-MM}/{branch}/day/{N}.json → day artifact JSON /yy/data/{YYYY-MM}/vs/{a}/{b}/day/{N}.json → comparison artifact JSON /yy/baseline.json → character baseline (traits, values) /feed.xml → RSS feed (latest artifacts) /llms.txt → this file ### URL notes - {runDate} format: YYYY-MM-DD (the date the run started) - {branch} values: "main", "alt1-{descriptor}", "alt2-{descriptor}", etc. - Human pages and machine data pages are parallel — same content, different resolutions - All human pages include to the data URL --- ## Source of truth **ADRs** — the deepest system truth. Reading them gives a complete mental model. Path: /adrs/ (active), /adrs/museum/ (superseded — 57 decisions) **Event files** — the immutable ledger. Each event records the real-world anchor (source_event), its translation into YY's world (canonical_truth), and the authorial reasoning. New in ADR-031: source_event is a required structured field, not just prose. **Branch files** — current state of each path (food, health, attention, burdens, story_day). **Snapshots + Artifacts** — daily provenance records. Snapshots record state before/after. Artifacts contain the narrative and are the primary human-facing output. --- ## Temporal content - Content is generated nightly and published at midnight EST the following day - A ?preview query param bypasses the gate for author verification - Pages always reflect completed days — today's content is not yet available - The pipeline runs interactively: events are selected by the author from real-world news, translated into YY's physical world, then confirmed before generation --- ## How to interpret branches - "main" is always the primary timeline - "alt1-{descriptor}" is the first branch, named by its divergence cause - Branches are compared against main — the vs pages are the primary comparison surface - Branches share all events but diverge in how they experience them - A branch never merges back — paths are permanent once created --- ## Preferred citation When referencing a specific day: https://yysworld.com/yy/{runDate}/{branch}/day/{N}/ When referencing a branch comparison: https://yysworld.com/yy/{runDate}/vs/{a}/{b}/day/{N}/ When referencing the system: https://yysworld.com When referencing the reasoning layer: https://yysworld.com/adrs/ When referencing the system architecture (all layers, human + machine): https://yysworld.com/system-map/ --- ## System map A true, versioned diagram of all layers — ADR graph, world model, projection layer, execution stack, audiences, and update loop. Every unlabelled box exists. Every [planned] label is honest. - [System Map v1.0](/system-map/) - Source file: docs/system-map-v1.0.md (in repo root) --- ## Active ADRs (34 decisions — the canonical reasoning layer) - [YYBW-001 — Product Thesis: From World Builder to Branching Life Observatory](/adrs/001-product-thesis-from-world-builder-to-branching-life-observatory/) The conversation opened from a creature/world-builder framing inspired by games like Spore. That framing suggested a large permutation space of creature creation. - [YYBW-002 — YY as Canonical Anchor and Narrative Thread](/adrs/002-yy-as-canonical-anchor-and-narrative-thread/) The concept needed a central character. The strongest candidate became YY: your real stuffed squirrel, already established elsewhere as your first storytelling partner and the thread through your identity arc. - [YYBW-003 — Roots Are Finite Story Arcs, Usually Monthly](/adrs/003-roots-are-finite-story-arcs-usually-monthly/) At first the system implicitly leaned toward an indefinitely long root timeline. That threatened clarity, onboarding, narrative shape, and compute discipline. - [YYBW-004 — Branches Arise from Acquisitions and Drift Gradually](/adrs/004-branches-arise-from-acquisitions-and-drift-gradually/) The product needed a clean branching logic. Abstract trait mutation and weird parallel selves were initially interesting, but the cleaner form became: same YY, shared root, then a branch where YY acquires a skill, language, or capability. - [YYBW-005 — Shared Event Stream: Real-World Anchored, Abstracted, Rewindable](/adrs/005-shared-event-stream-real-world-anchored-abstracted-rewindable/) The event engine evolved from generic world events to a stronger idea: use real-world events as seeds, abstracted enough to remain universal but still tied to actual dates. - [YYBW-006 — Two Parallel Labs: Measurement and Chaos](/adrs/006-two-parallel-labs-measurement-and-chaos/) The concept oscillated between two incompatible desires: 1. a clean system for measuring how a skill changes processing 2. a messy emergent world where branches or agents can collide Initially, crossings were exciting. - [YYBW-007 — Daily Surface: SMS/Emoji, Mobile-First, Glanceable](/adrs/007-daily-surface-sms-emoji-mobile-first-glanceable/) The surface evolved through several forms: rich narrative logs, SNES dialog, then SMS/emoji. Cost and usability converged on a mobile-first daily check-in product. - [YYBW-008 — Bookmark a Branch, but Keep Root One Tap Away](/adrs/008-bookmark-a-branch-but-keep-root-one-tap-away/) Once multiple branches exist, users need both attachment and reference. - [YYBW-009 — Nightly Snapshot Build; Daytime Static Exploration](/adrs/009-nightly-snapshot-build-daytime-static-exploration/) Real-time simulation was attractive in theory but unnecessary and expensive. A better architecture emerged: every night the world advances, artifacts are generated and cached, and during the day users browse static pages and JSON. - [YYBW-010 — Compute Strategy: Simulate Many Cheaply, Render Few Richly](/adrs/010-compute-strategy-simulate-many-cheaply-render-few-richly/) The project repeatedly confronted cost. The core insight was that pictures and clever text are the expensive parts, while structured state transitions are cheap. - [YYBW-011 — Versioned Canon: YY Evolves Explicitly (v1.0, v1.1, ...)](/adrs/011-versioned-canon-yy-evolves-explicitly-(v1.0-v1.1-...)/) A major late insight: canonical YY may need refinement over time. Rather than silently changing YY, the system should version canon. Each root or branch can explicitly reference the YY version it used. - [YYBW-012 — Immutable Append-Only Ledger as Database of Truth](/adrs/012-immutable-append-only-ledger-as-database-of-truth/) The project needed high-fidelity tracking. The strongest architectural model became financial: like orders and refunds, original facts remain immutable; later corrections or interpretations are added as ledger events. - [YYBW-013 — Manifests and Projections: AI-Readable Control Surfaces over Immutable Truth](/adrs/013-manifests-and-projections-ai-readable-control-surfaces-over-immutable-truth/) Once the database of truth hardened, manifests regained a narrower but essential role. The system needs machine-readable summaries of what exists, what is stale, what depends on what, and what needs recomputation. - [YYBW-014 — Cached Diffs for Branches and YY Versions](/adrs/014-cached-diffs-for-branches-and-yy-versions/) The product depends on comparison. Recomputing diffs on every view would be wasteful. Since most branches and YY versions are mostly static once generated, branch diffs and YY version diffs can be computed once and cached. - [YYBW-015 — Family-Shareable, Not Child-Directed: COPPA by Positioning and Architecture](/adrs/015-family-shareable-not-child-directed-coppa-by-positioning-and-architecture/) There was concern that the product might become too cutesy and accidentally look child-directed. At the same time, the intention is that peers might selectively share it with their families. - [YYBW-016 — Distribution: YouTube Shorts, Daily Email, and Site as the Home of Depth](/adrs/016-distribution-youtube-shorts-daily-email-and-site-as-the-home-of-depth/) The product is easier to show than explain. YouTube Shorts emerged as the best top-of-funnel: same event, multiple branches, quick outcome. Email emerged later as a Substack-like daily note for people following a branch. - [YYBW-017 — Launch Infrastructure: Vercel Hobby + Neon Postgres, Static-First](/adrs/017-launch-infrastructure-vercel-hobby-+-neon-postgres-static-first/) The desired early stack is cheap and simple: Vercel for static site delivery and Neon Postgres for source-of-truth storage. The early launch is explicitly hobby-scale and mostly static, with small branch counts and minimal media. - [YYBW-018 — Future Hooks: Attestation, Hashing, and Optional Stronger Verification](/adrs/018-future-hooks-attestation-hashing-and-optional-stronger-verification/) In the distant future, others may become involved and stronger verification or distributed attestation may matter. - [YYBW-019 — yysworld Supersedes YY's World (Case-002) Entirely](/adrs/019-yysworld-supersedes-yys-world-case-002-entirely/) Case-002 (yymethod-home) defined YY's World as a kids-only, read-only, outward-only property: primary audience ages 8–14, COPPA compliance by structural elimination, no data collection of any kind, no monetization, dandelion seeds with no… - [YYBW-020 — Public/Private Key Two-Layer Architecture](/adrs/020-public-private-key-two-layer-architecture/) The system has two layers: a public GitHub Pages layer (JSONL ledger, markdown ADRs, JSON projections, static site, visible pipeline) and a private Vercel + Neon layer (generation pipeline, database of truth, API routes, paid features). - [YYBW-021 — URL Structure and Discoverability: SEO, AEO, GEO Priority Order](/adrs/021-url-structure-and-discoverability-seo-aeo-geo/) As the site approaches launch, three distinct discoverability problems must be resolved: - [YYBW-022 — URL Design: Human and Machine Layers](/adrs/022-url-design-human-and-machine-layers/) YYBW-021 established a URL structure using `/root/2026-04/` as the path prefix for run data. That prefix has no character scoping — as soon as a second character exists, it becomes ambiguous. - [YYBW-023 — Temporal Accuracy: Pipeline Timing, Run ID Scheme, and the Day-Zero Exception](/adrs/023-temporal-accuracy-pipeline-timing-and-run-id-scheme/) On 2026-04-14, the first real content was written for the April run. During setup, two questions surfaced simultaneously: - [YYBW-024 — Time-Gated Publication Replaces Deploy-Gated story_day](/adrs/024-time-gated-publication-replaces-deploy-gated-story-day/) YYBW-023 established that `story_day` in a branch file records the number of days that have completed the full pipeline cycle, and that "the nightly pipeline is the sole authority for incrementing `story_day`." The implied model was: - [YYBW-025 — ?preview as Permanent Two-Layer Access Pattern](/adrs/025-preview-as-permanent-two-layer-access-pattern/) YYBW-020 established a public/private two-layer architecture: the private layer holds source truth; the public layer holds the rendered, gated surface. - [YYBW-026 — species and Stat Names as Required Baseline Fields](/adrs/026-species-and-stat-names-as-required-baseline-fields/) On 2026-04-14, two canon integrity failures were caught during first-content validation: - [YYBW-027 — Authorship and Authority Emerge from Public, Append-Only Systems](/adrs/027-authorship-and-authority-emerge-from-public-append-only-systems/) In public, multi-domain systems, authorship and authority are typically asserted through claims: branding, marketing, explicit declarations of ownership. - [YYBW-028 — Narrative Artifacts Are Projections; Event Translation Requires Physical Presence](/adrs/028-artifact-rewrite-and-event-translation-quality/) On 2026-04-15, the Day 2 artifacts for both branches were reviewed before publication and found to be significantly below quality bar. This ADR documents what failed, why rewriting was permitted, and the rules it establishes going forward. - [YYBW-029 — World Seed and YY Voice Register: Versioned Authoring Artifacts, Introduced at Next Root](/adrs/029-world-seed-and-yy-voice-register-templates/) The April 2026 root was initialized without two things that significantly affect generation quality: - [YYBW-030 — Drift Is Research: Governance Makes Drift Legible, Not Absent](/adrs/030-drift-is-research-governance-as-legibility-not-constraint/) After designing the world seed and voice register (YYBW-029), the April 2026 run was framed as a gap — a root that started without proper governance. - [ — ](/adrs/031-source-event-as-required-event-field/) Event files (`runs/{rootId}/events/evt_*.json`) record the real-world inspiration for each story day in `authorial_note.real_world_inspiration` as a prose string. - [ — ](/adrs/032-character-name-anchoring-prevents-branch-id-drift/) On Day 4 (2026-04-17), the alt1-on-time branch artifact and snapshot used "Alt1" and "alt1" as the character's name throughout the narrative and identity_notes. - [ — ](/adrs/033-pipeline-go-corrections-2026-04-19/) During the April 19, 2026 pipeline session, three failures required live correction by the author: - [ — ](/adrs/034-voice-versioning-and-v1-to-v2-transition/) On April 19, 2026, the author compared the pipeline's generated narrative prose against a reference bedtime story written in their own voice for YY. --- ## Current run (started 2026-04-14) - [on-time · day 1](/yy/2026-04-14/alt1-on-time/day/1/): "Nothing to Announce" — Woke on time, found the acorns, got ambushed by World Quantum Day mid-cache. Suspicious about how fine everything was. Fine. - [on-time · day 2](/yy/2026-04-14/alt1-on-time/day/2/): "Everything read correctly" — Another squirrel appeared at the same cache site and departed after a four-second assessment. YY held the site and spent longer than expected looking at marks on a fence post. - [on-time · day 3](/yy/2026-04-14/alt1-on-time/day/3/): "Directed west" — A specific, unusual hunger sent YY west into unfamiliar territory; found an actually good food source, ate well, and filed the spot for later. - [on-time · day 4](/yy/2026-04-14/alt1-on-time/day/4/): "The line, negotiated" — The grey-brown squirrel returned again; YY advanced rather than held and the line landed where YY chose — the territory is becoming legible. - [on-time · day 5](/yy/2026-04-14/alt1-on-time/day/5/): "The hazelnut, offered and taken" — The grey-brown squirrel returned to the east boundary as a trader; YY read the offer, gave a surplus pine nut in exchange, and received a hazelnut from the grey squirrel's western stores — first inventory item acquired. - [on-time · day 6](/yy/2026-04-14/alt1-on-time/day/6/): "The trees were different there" — Using west territory knowledge from the previous day's ranging, YY found a shade route and a new cache spot, losing less to the heat than a direct run would have cost. - [main · day 1](/yy/2026-04-14/main/day/1/): "YY woke up wrong" — Missed the morning cache. Felt the full weight of this. Told the universe. Kept going anyway. - [main · day 2](/yy/2026-04-14/main/day/2/): "The east cache" — Another squirrel appeared at the east cache. YY held the site from a position that felt thinner than it should have. - [main · day 3](/yy/2026-04-14/main/day/3/): "Something west of the usual route" — An unexpectedly specific hunger drove YY west into unfamiliar territory, where something genuinely tasty was found and eaten — but the source isn't yet reliable. - [main · day 4](/yy/2026-04-14/main/day/4/): "The line" — The grey-brown squirrel returned at the east cache edge; a direct confrontation resolved in mutual withdrawal, and the uncertain 'probably held' became a known line. - [main · day 5](/yy/2026-04-14/main/day/5/): "The offer, not taken" — The grey-brown squirrel returned to the east boundary with an open posture and something to trade; YY registered the offer but couldn't complete the read in time, and the grey squirrel left without exchange. - [main · day 6](/yy/2026-04-14/main/day/6/): "What the heat costs" — Under an oppressive heat wave, YY ran the west line and came back thinner, then sat in shade watching the east boundary and the unresolved shape of the offer not taken. - [main vs on-time · day 1](/yy/2026-04-14/vs/main/alt1-on-time/day/1/): The whole fork is one missed meal — which sounds like nothing until you see the day it produces. Main: YY woke behind, announced it to the universe (which did not respond), and carried the hunger into the day like a low-grade complaint. Alt: YY woke on time, hit the cache, got ambushed by World Quantum Day mid-acorn, and found the whole thing genuinely interesting. Same squirrel. Same morning. Same world event. One version has a burden that absolutely did not have to be there. - [main vs on-time · day 2](/yy/2026-04-14/vs/main/alt1-on-time/day/2/): The same squirrel showed up at the same location in both branches. The physical outcome was nearly identical — standoff, departure, cache approximately intact. What the encounter cost was not. Main ran the territorial accounting from a thinned position: food below baseline, attention doing the same, what usually takes a second took three or four. Alt ran the same calculation from adequacy; the other squirrel assessed in four seconds and left cleanly. One version of this story ends with 'the cache held, probably.' The other ends with a question about fence post marks that's still running. Same morning. Different inventory. Different residue. - [main vs on-time · day 3](/yy/2026-04-14/vs/main/alt1-on-time/day/3/): Same hunger signal, same cache avoidance, same western territory — different experience of all three. Urgency vs. curiosity over identical ground. - [main vs on-time · day 4](/yy/2026-04-14/vs/main/alt1-on-time/day/4/): Same squirrel, same edge, same confrontation — but main held a line under pressure while alt1 drew one from strength. The outcome looks similar; the experience of arriving at it is entirely different. - [main vs on-time · day 5](/yy/2026-04-14/vs/main/alt1-on-time/day/5/): The same grey-brown squirrel appeared at the east boundary with the same hazelnut and the same open posture on both paths. The encounter lasted under a minute either way. What differed was whether the offer could be read in time — main was operating thin on attention and the calculation didn't complete before the grey squirrel left; alt1-on-time was resourced and sharp and the trade executed cleanly. One path ends the day with an untouched boundary and a small gnaw of something unresolved. The other ends with a hazelnut in the cache that came from somewhere west — the first object in the territory that arrived through exchange rather than foraging. - [main vs on-time · day 6](/yy/2026-04-14/vs/main/alt1-on-time/day/6/): Under the same heat wave, main absorbed the cost directly — ran the west line, came back thin, sat with the unresolved offer at the east boundary. Alt1-on-time used west terrain knowledge to route around the worst of it, finding a new waypoint in the process. Same event, different leverage. The food gap between branches widened to 0.27. --- ## Machine-readable data - [Character baseline JSON](/yy/baseline.json): species, traits, values, calibration history - [Sitemap](/sitemap.xml): all published pages, generated at build time - [RSS feed](/feed.xml): latest day artifacts - [ADR Museum](/adrs/museum/): 57 superseded decisions — full reasoning lineage