feat: add Thirty-day Sap Ledger (#100)

Author: hyeonsangjeon

AGENTS.md

@@ -30,7 +30,7 @@ CDN import map (Three.js r0.160 via jsDelivr) plus local data, scripts, and modu
 |---|---|---|
 | **`index.html`** | Primary app runtime — 3D engine, UI, navigation, residents, exploration, i18n, day/night. | Any UI / gameplay / client behavior change. |
 | **`repolis.config.js`** | Fork-facing runtime identity and optional-service policy. GitHub Pages infers the fork owner; upstream Workers stay off on forks. | Changing owner inference, template behavior, or canonical endpoints. |
-| **`repos.json` + `data/city-state.json`** | Generated repo catalog plus deterministic era, season, statistics, sap timestamp, and archived roots for the current owner city. **Do not hand-edit.** | Never directly; regenerate (see below). |
+| **`repos.json` + `data/city-state.json`** | Generated repo catalog plus deterministic era, season, current statistics, Silence Ledger, bounded 30-day Sap Ledger, sap timestamp, and archived roots for the current owner city. **Do not hand-edit.** | Never directly; regenerate (see below). |
 | **`data/city-state.schema.json`** | Strict JSON Schema for the generated city-state artifact. | Changing the city-state contract. |
 | **`assets/city-time.js`** | Pure wear (`recent` / `faded` / `mossed`), ruin, reference-date, and seasonal palette rules. | Changing how public time metadata affects the city. |
 | **`data/lore/fragments.json` + `assets/lore-fragments.js`** | Hand-authored KO/EN elder fragments plus strict validation, deterministic active-roster allocation, and session-bounded delivery. | Changing The Silence fragments or their rarity/allocation contract. Never generate or overwrite the JSON. |
@@ -39,7 +39,7 @@ CDN import map (Three.js r0.160 via jsDelivr) plus local data, scripts, and modu
 | **`scripts/fork_lineage.py` + `assets/fork-lineage.js`** | Public-only fork source sanitizer plus deterministic six-color crest projection. | Changing generated fork source truth, lineage cards, or the shared crest batch. |
 | **`scholars.js`** | `window.SCHOLARS` roster: POLARIS · VEGA · RIGEL · MIRA · LYRA. | Adding / editing an NPC scholar. |
 | **`assets/world-tree/createRepolisHero.js`** | Procedural World Tree factory imported by `index.html`. | Changing the tree geometry, materials, sockets, or actions. |
-| **`assets/world-tree/world-tree-state.js`** | Pure projection for Chronicle, Silence Ledger, Roots, sap-flow freshness/mode, bounded star/repo growth, and portable public-town residents. | Changing how owner or normalized public-town state reaches the silent World Tree and local resident roster. |
+| **`assets/world-tree/world-tree-state.js`** | Pure projection for Chronicle, Silence Ledger, 30-day Sap Ledger, Roots, sap-flow freshness/mode, bounded star/repo growth, and portable public-town residents. | Changing how owner or normalized public-town state reaches the silent World Tree and local resident roster. |
 | **`assets/repo-portal.js`** | Pure username/repository parser, route precedence, public projection, canonical Portal URL, and owner-town expansion link. | Changing `?repo=`, accepted GitHub inputs, public traffic truth, or target share links. |
 | **`assets/repo-route.js`** | Pure 2–3 stop route validator, current-catalog resolver, conflict policy, and canonical Repo Route URL. | Changing visitor-curated multi-repo paths or `?route=` links. |
 | **`assets/contribution-quests.js`** | Pure current-owner/catalog issue projector and bounded quest ranker. | Changing Open Source Quest validation, tier priority, or result diversity. |
@@ -184,6 +184,7 @@ Tested on Node v24. There is no linter or formatter configured — match the sur
 | Change Town Growth Replay years, camera, reveal, share links, or era postcards | `assets/town-growth.js` + `/*TOWN_GROWTH_REPLAY*/` in `index.html` + the Growth Replay group in `scripts/smoke.mjs`; creation dates are historical, building metrics are current, and replay must restore camera/fog/sky/LOD exactly. |
 | Change Repository Atelier room, avatar, data walls, or action terminals | `/*REPOSITORY_ATELIER*/` in `index.html` + the Atelier group in `scripts/smoke.mjs`; preserve one lazy reusable room, three bounded canvas atlases, exact exterior restore, zero exterior renders inside, in-room Ask/Why ownership, and explicit-only exit/GitHub navigation. |
 | Change adaptive frame thresholds or visual tiers | `/*VISUAL_GOVERNOR_CORE*/` + `/*VISUAL_GOVERNOR_RUNTIME*/` in `index.html`, `scripts/test-visual-governor.mjs`, and the matching smoke group; preserve 6 s eligible warm-up, separated hysteresis/dwell, balanced-before-lean ambient ordering, LOW_END/reduced-motion authority, state continuity, and zero storage/network/telemetry. |
+| Change the 30-day Sap Ledger fields, retention, or Chronicle summary | `scripts/city_state.py` + `data/city-state.schema.json` + `assets/world-tree/world-tree-state.js` + `/*WORLD_TREE_CHRONICLE*/` in `index.html`; preserve actual UTC entries only, same-day replacement, 30-entry/32 KiB caps, public aggregate privacy, and unavailable foreign history. |
 | Change Twin Towns matching or two-person share links | `assets/twin-towns.js` + the Twin Towns block in `index.html` + `scripts/smoke.mjs`. |
 | Change Town Gazette / return-visit freshness | `/*FRESHNESS*/` + Passport render/start flow in `index.html`; keep snapshots local, bounded, per-town, and explicit-read only. |
 | Change resident homes, styles, gardens, routines, moods, friendships, haunts, or Shared Joy | The resident social layer + Starlight Row blocks in `index.html`; preserve the resident style map, 3 roof batches, 10/6 desktop/LOW_END detail-batch cap, 42-unit reserve, entrance gap, quarter colliders, home/work truth, owned porch seats, and social ownership guards. |
@@ -204,7 +205,7 @@ Tested on Node v24. There is no linter or formatter configured — match the sur
 A daily Action turns the owner's **public repos + committed traffic logs** into `repos.json`; included public
 forks may also carry a minimal canonical source record. `index.html`
 turns that array into metric-shaped buildings, topic districts, routes, maps, and exploration progress.
-Residents add named homes, home/work commutes, moods, friendships, haunts, Shared Joy excursions, gatherings, and festivals. Foreign `?user=` and Repo Portal towns run the same pure portable projection after their one existing public load, deriving their own era, season, Silence Ledger, Roots, and 6/4-capped local resident roster without owner traffic, memories, services, or extra requests. The oldest eligible 20% of the owner roster can rarely let slip a hand-authored local lore fragment; repositories younger than 90 reproducible-clock days receive a lightweight construction layer and newcomer voice. Landmarks include the Contribution Library, Chronopolis, Observatory, and imported procedural World Tree. Repo Portal lets one public `owner/repo` arrive before its owner catalog, then reuses the same building and Repository Atelier with truthful public-metadata boundaries. Repo Route lets a visitor hand off an ordered 2–3 house path they actually explored. Open Source Quests connects an explicitly loaded current public issue to its real repo house before GitHub handoff. Every repo also rebinds one reusable Atelier where its data, impact signals, current avatar, and in-room Gitber stay inside the exhibition. Town Growth Replay turns public repo creation dates into a reversible, shareable city history without inventing historical metrics. Gitber/POLARIS and the
+Residents add named homes, home/work commutes, moods, friendships, haunts, Shared Joy excursions, gatherings, and festivals. The owner World Tree retains at most 30 actual UTC daily public aggregate entries in its Sap Ledger; same-day refreshes replace, missing days stay missing, and no browser or traffic data enters it. Foreign `?user=` and Repo Portal towns run the same pure portable projection after their one existing public load, deriving their own era, season, Silence Ledger, Roots, and 6/4-capped local resident roster without owner history, traffic, memories, services, or extra requests. The oldest eligible 20% of the owner roster can rarely let slip a hand-authored local lore fragment; repositories younger than 90 reproducible-clock days receive a lightweight construction layer and newcomer voice. Landmarks include the Contribution Library, Chronopolis, Observatory, and imported procedural World Tree. Repo Portal lets one public `owner/repo` arrive before its owner catalog, then reuses the same building and Repository Atelier with truthful public-metadata boundaries. Repo Route lets a visitor hand off an ordered 2–3 house path they actually explored. Open Source Quests connects an explicitly loaded current public issue to its real repo house before GitHub handoff. Every repo also rebinds one reusable Atelier where its data, impact signals, current avatar, and in-room Gitber stay inside the exhibition. Town Growth Replay turns public repo creation dates into a reversible, shareable city history without inventing historical metrics. Gitber/POLARIS and the
 scholars (VEGA · MS Learn, RIGEL · DeepWiki, MIRA · Context7, LYRA · Hugging Face) add natural-language
 navigation and grounded answers. Residents hand specialist questions to the right scholar instead of gaining
 their own MCP access. Gitber remains the only all-district traveler: ride observations and Shared-state answers are local, while household memory questions return to the correct repo home. The Passport's local Town Gazette makes daily public-repo changes visible on return. Everything

CHANGELOG.md

@@ -6,6 +6,23 @@ The format loosely follows [Keep a Changelog](https://keepachangelog.com/); date
 This file keeps the current product era (`1.50.0` onward) easy to scan. Earlier releases are preserved in
 [`docs/changelog-archive.md`](docs/changelog-archive.md).
 
+## [1.94.0] — 2026-08-26
+
+### 🌱 Thirty-day Sap Ledger — bounded aggregate city history
+
+- Generated city state now carries `repolis.sap-ledger` v1: up to 30 unique, ascending UTC daily owner-town
+  entries and 32 KiB compact UTF-8. Same-day reruns replace, later runs append, missing dates remain absent,
+  and the generator refuses fabricated backfill behind the latest actual entry.
+- Each entry stores only public city aggregates: repository/archive counts, covered star/fork totals,
+  inclusive latest-public-push activity over 30 days, season, and same-date Silence Ledger counts. Missing
+  star/fork inputs produce `null` totals; traffic, private infrastructure, work titles, messages, dialogue,
+  identity, and browser state are excluded.
+- The existing World Tree Chronicle adds one compact KO/EN summary. One entry reports only its start date;
+  later entries compare the latest two actual dates and state overall gaps. Foreign public towns explicitly
+  report history unavailable and never reuse the canonical owner ledger.
+- The generated payload remains the only cold-load source: no runtime request, backend, Worker, analytics,
+  storage, model call, dependency, build step, scene object, or visual asset was added.
+
 ## [1.93.0] — 2026-08-26
 
 ### 🎛️ Adaptive Visual Governor — preserve detail within the frame budget

README.ko.md

@@ -82,6 +82,7 @@ Repolis는 공개 GitHub 메타데이터와 누적 트래픽을 또 하나의 
 
 - **주민은 제자리 반복 동작만 하지 않습니다.** 이름 있는 주민들이 자기 구역을 거닐고, 시간대에 맞춰 생활하며, 기분이 바뀌고, 아끼는 아지트를 찾습니다. 북동쪽 **별빛 주거구역**에는 이름표가 달린 집과 주민색 앞마당이 있습니다. 집마다 3종 지붕 실루엣, 셔터, 트랜섬 창, 선택형 창가 화분·캐노피·굴뚝·지붕 장식이 다르게 조합되고, 공동 꽃정원·랜턴·생울타리·활엽수·사이프러스가 마을을 감쌉니다. 밤이면 따뜻한 창과 현관으로 귀가하고, 아침이면 각자 구역으로 출근합니다. 친구를 알아보고 함께 산책하거나 나란히 쉬며, 모닥불에 모이고, 때로는 새 릴리스 축제를 엽니다. 두 주민은 플레이어 지시나 AI 호출 없이 실제 꽃밭·별이 보이는 밤하늘·실제 레포 집으로 짧은 **함께하는 기쁨** 나들이도 스스로 떠납니다. 전문 질문을 받으면 아는 척하지 않고 맞는 현자를 소개합니다. 나침반을 따라 마을 안에서 그 현자를 직접 찾아가세요.
 - **공개 마을도 자기 기록으로 살아갑니다.** 기존 공개 레포 요청 한 번으로 도시력·계절·고요 장부·아카이브된 The Roots와 데스크톱 최대 6명/휴대폰·LOW_END 최대 4명의 주민을 결정적으로 만듭니다. 주민의 일·인사·실제 레포 집 연결은 공개 필드만 쓰며, 트래픽·주인 주민·Shared/Bound 기억은 알 수 없는 값으로 남깁니다. 실시간 연결과 근거 검색 서비스도 꺼져 있어 두 번째 API 요청이나 모델 호출이 없습니다.
+- **주인 마을의 세계수는 작고 사실적인 이력을 남깁니다.** **30일 수액 장부**에는 공개 레포·스타·포크·최근 활동·계절·고요 집계의 실제 UTC 일별 기록만 최대 30개 보존됩니다. 같은 날 재실행하면 중복 대신 교체하고, 누락 날짜는 그대로 두며, 다른 공개 마을에는 주인 장부를 넘기지 않습니다.
 - **탐험에는 흐름이 남습니다.** 탐험 여권이 집과 명소 방문을 기록하고, 구역 진행률이 남은 곳을 보여주며, 매일 열리는 **마을 이야기**가 한 주민과 그 아지트, 실제로 이어진 레포 또는 구역을 연결합니다.
 - **도시는 실제 기여로 이어집니다.** **오픈소스 퀘스트**는 방문자가 직접 요청할 때만 익명 GitHub 공개 검색을 한 번 실행해 현재 `good first issue`, `help wanted`, 일반 열린 이슈 중 최대 세 개를 고릅니다. 실제 레포 집을 거친 뒤 정확한 이슈로 연결하며, 결과는 탭에만 남습니다. 로그인·토큰·이슈 추적·새 백엔드는 없고, 기존 Star 초대는 방문자가 이슈 열기를 선택한 뒤에만 나타날 수 있습니다.
 - **방문자가 도시의 가치를 증명한 동선을 그대로 건넬 수 있습니다.** 레포 집을 연 뒤 **Repo Route**에 2~3곳을 순서대로 담으면, 수신 링크가 입장 전에 정류장을 확인해 주고 실제 집을 차례로 가리킵니다. 기존 Star 초대는 이 길을 완주한 뒤에만 열립니다. 초안은 세션에만 있고 URL에는 공개 레포 이름만 들어가며, 백엔드·계정·저장 키·렌더 자산을 추가하지 않습니다.

README.md

@@ -82,6 +82,7 @@ At ordinary walking distances, a one-draw architectural LOD keeps each repo hous
 
 - **Residents have lives, not idle loops.** Named townspeople wander their districts, keep daily rhythms, carry changing moods, visit cherished haunts, recognize friends, stroll and sit together, gather around the campfire, and sometimes celebrate a recent repository release. Their cottages form **Starlight Row** on the north-east edge, with resident-coloured gardens, three roof silhouettes, shutters, transoms, selected window boxes, canopies, chimneys, and roof finials. A shared flower bed, lanterns, hedges, and broadleaf/cypress trees care for the commons. Night brings residents home to warm windows and porch seats, while morning sends them back to their district work. Pairs also choose their own short **Shared Joy** excursions to real flower patches, visible night stars, or a real repo house—without a player prompt or AI call. Ask a specialist question and they introduce the right scholar instead of pretending to know: follow the compass and find that scholar in the world.
 - **A public town lives from its own record.** The one existing public-repository load deterministically supplies its era, season, Silence Ledger, archived Roots, and up to six desktop/four phone-or-LOW_END residents with local jobs, greetings, and real repo-home bindings. Traffic, owner residents, Shared/Bound memories, realtime, and grounded services stay unknown or off; no second API request or model call is made.
+- **The owner World Tree keeps a small factual history.** Its **Thirty-day Sap Ledger** retains up to 30 actual UTC daily entries of public repo, star, fork, recent-activity, season, and Silence aggregates. Same-day refreshes replace instead of duplicate, missing days stay missing, and foreign towns explicitly receive no owner ledger.
 - **Exploration has continuity.** The Explorer Passport records houses and landmarks, district progress shows what remains, and the daily **Village Chronicle** connects one resident to their cherished haunt and a truthful related repo or district.
 - **The city points outward to real work.** **Open Source Quests** makes one anonymous public GitHub search only when the visitor asks, ranks up to three current `good first issue`, `help wanted`, or open issues, and leads through the actual repository house before the exact issue handoff. Results stay in the tab; no login, token, issue tracking, or new backend is involved. The existing earned Star invitation can appear only after the visitor chooses to open an issue.
 - **A visitor can hand off the route that proved the town's value.** After opening a repository house, **Repo Route** can save it to an ordered 2–3 stop walk. The recipient's link confirms the stops before entry, points to each real house in sequence, and offers the existing earned Star invitation only after completion. The draft is session-only; the URL contains public repo names and adds no backend, account, storage key, or render asset.