---
schema_version: 1
type: "project"
id: "project-shard"
slug: "shard"
title: "Shard"
summary: "A finite generative narrative system where models imagine scenes while deterministic code owns identity, history, time, chance, and ending gates."
proposition: "The model imagines. The code keeps the books."
status: "published"
visibility: "public"
indexing: "index"
project_kind: "narrative-experiment"
project_state: "evolving"
role: "Product and system design"
technologies:
  - "TypeScript"
  - "event sourcing"
  - "language models"
tags:
  - "AI architecture"
  - "narrative systems"
  - "game design"
created: "2026-03-03"
updated: "2026-07-23"
published: "2026-07-23"
canonical_path: "/projects/shard"
canonical_url: "https://rahilchamola.com/projects/shard"
preferred_citation: "Chamola, Rahil. “Shard: project case study.” Curated Randomness, 2026."
has_case_study: true
authors:
  - id: "rahil-chamola"
    name: "Rahil Chamola"
    role: "author"
---

# Shard

A finite generative narrative system where models imagine scenes while deterministic code owns identity, history, time, chance, and ending gates.

> The model imagines. The code keeps the books.

## Evidence boundary

This case study documents product and architecture decisions. It does not claim that the current system produces a better game or has passed a real-player validation gate.

## Case-study chapters

### 1. Structure without scripting. Freedom without chaos.

**The product tension.** The original wager was to preserve durable consequence without pre-authoring every branch.

### 2. The first v2 plan changed the cast, not the assumption.

**The redesign.** A real redesign began only when the product promise and the source of truth changed together.

### 3. World file, ledger, clock, plan.

**The kernel.** Four durable objects now carry the truths that narration is allowed to interpret but not overwrite.

### 4. Decide what the model is allowed to be wrong about.

**Responsibility.** Code, configuration, models, and evaluation own different questions and different failure modes.

### 5. A cleaner kernel is not evidence of a better game.

**What is not proven.** The architecture is inspectable. The emotional experience still needs durable evidence from real players.

## Decision timeline

### 2026-03-10 · Design the system before touching the AI

The game needed explicit types, world rules, and consequence handling before generation could be useful.

**Consequence.** V1 split generation into model roles and surrounded their output with typed governance.

**Sources.** Original public thesis; Original public architecture

### 2026-05-16 · A finite episode, but inherited machinery

The early redesign changed the experience frame while retaining three model roles, validators, effects, and contracts.

**Consequence.** It became evidence that a redesign can preserve the assumption that made the first system difficult.

**Sources.** Superseded redesign

### 2026-06-09 · Optimize for a finite emotional story

The desired outcome became a story that moves the player and leaves memorable characters, not a simulation that can continue forever.

**Consequence.** Pacing, memory, privacy, and closure became architectural constraints.

**Sources.** Current product contract

### 2026-06-20 · Move durable truth into an append-only ledger

History and causality need one inspectable source rather than several mutable interpretations.

**Consequence.** Relationships, knowledge, promises, and inventory can be derived as views over accepted events.

**Sources.** Current product contract; Current ledger contract

## System

Player intent enters deterministic scene code with the world file and finite plan. The scene model returns prose and proposed events. Code validates references, applies accepted events to the append-only ledger, and derives relationship, knowledge, promise, and inventory views. A separate asynchronous tick can read and extend wider world history.

### Nodes

- **Player intent** (view): The requested action or reply that begins a scene turn.

- **World file** (config): Authored canon, entities, locations, fixed points, and permitted variation.

- **Finite plan** (config): Story shape, current window, gates, and possible endings.

- **Scene engine** (code): Resolves deterministic checks, assembles context, and validates proposed references.

- **Scene model** (model): Imagines prose and proposes typed events inside the supplied context.

- **Append-only ledger** (data): The canonical, ordered record of accepted story events.

- **Derived views** (view): Relationships, knowledge, promises, inventory, and other readable state.

- **World tick** (code): An asynchronous path that advances the wider world away from the player's scene.

### Edges

- Player intent -> Scene engine: attempt (explicit)

- World file -> Scene engine: canon (explicit)

- Finite plan -> Scene engine: window and gates (explicit)

- Scene engine -> Scene model: validated context (explicit)

- Scene model -> Scene engine: prose and proposals (explicit)

- Scene engine -> Append-only ledger: accepted events (explicit)

- Append-only ledger -> Derived views: derive (derived)

- Append-only ledger -> World tick: history (async)

- World tick -> Append-only ledger: world events (async)

## Counting frames

These values use different definitions. They document changing architectural vocabulary, not an apples-to-apples reduction benchmark.

- **54+ · Public March claim:** Effect types named by the historical public project page. Source: Historical project page.

- **73 · March type union:** Unique effect spellings in the reviewed union, including aliases and deprecated kinds. Source: March implementation snapshot.

- **28 · V2 retrospective:** The later design document's retrospective description of the v1 effect bus. Source: Current product contract.

- **12 · V2 ledger:** Canonical event kinds in the current ledger contract. Source: Current ledger contract.

## Canonical ledger event kinds

- scene
- move
- dialogue
- fact
- feeling
- item
- bond
- promise
- clock
- arrival
- departure
- consequence

## Responsibility boundary

### Code

- identifiers and reference validity
- dice, time, ordering, and plan gates
- accepted event application

**Limit.** It cannot decide whether a scene is moving or beautifully written.

### Configuration

- world canon and fixed points
- difficulty, resistance, and permitted variation
- story shape and authored constraints

**Limit.** It provides a possibility space, not the final moment-to-moment story.

### Model

- interpretation and scene construction
- dialogue, texture, and proposed meaning
- narrative choices inside current constraints

**Limit.** It does not own durable truth, dice, identity, or reference validity.

### Evaluation

- coherence and experience review
- real-player observation
- whether the story creates attachment and desire to return

**Limit.** A fluent model or passing typecheck cannot certify the human outcome.

## Claim ledger

### Shard was designed as a third option between authored branching and unconstrained chat.

**Assessment:** documented

The March public series states this product wager directly and describes the TypeScript-first architecture built to support it.

**Sources.** Original public thesis; Original public architecture

### V2 implements twelve canonical ledger event kinds.

**Assessment:** documented

The current type contract defines scene, move, dialogue, fact, feeling, item, bond, promise, clock, arrival, departure, and consequence.

**Sources.** Current product contract; Current ledger contract

### The deeper change is from model-role architecture to truth-boundary architecture.

**Assessment:** interpretation

V1 specialized model jobs and repaired their output. V2 first asks which facts are deterministic, then gives the model a narrower creative seam.

**Sources.** Original public architecture; Superseded redesign; Current product contract

### The design pressures every story toward an ending, but a universal guarantee is not established.

**Assessment:** unresolved

The code includes plans and ending gates. The reviewed implementation can still depend on a model reporting that an ending occurred.

**Sources.** Current product contract; Current scene path

### Real-player validation is still an open evidence gate.

**Assessment:** unresolved

The repository contains synthetic testing infrastructure, but the reviewed artifacts do not establish that the planned real-player gate occurred.

**Sources.** Experience evidence plan; Game-design review

## What transfers

1. Name the human outcome before selecting a model topology.
2. Separate model, code, configuration, and evaluation responsibilities.
3. Keep one append-only record when history and causality matter.
4. Validate what code can know and evaluate what people must feel.
5. Keep sequential model calls off the critical path unless each one earns its cost and latency.
6. Design completion conditions for generative systems.

## Source ledger

- **Original public thesis:** Building Shard, Part 1: The Bet. Chamomo, 2026-03-10. States the third-option thesis, TypeScript-first design, and the claim that the LLM is the runtime rather than the product.

- **Original public architecture:** Building Shard, Part 2: Brain and Body. Chamomo, 2026-03-10. Documents model roles, the effect bus, coherence layers, and typed governance in the March system.

- **Historical project page:** Shard. Chamomo, 2026-03-10. Provides the public historical claim of 54-plus effect types.

- **March implementation snapshot:** V1 effect type union. Shard source snapshot, 2026-03-10. Exposes 73 unique spellings when aliases and deprecated kinds are included.

- **Superseded redesign:** Architecture: Shard v2. Shard v2 design record, 2026-05-16. Retains a three-model pipeline and much of the inherited governance machinery.

- **Current product contract:** Game Design: Shard v2. Shard v2 design record, 2026-06-09. Defines the finite emotional-story promise, four-part kernel, twelve-kind ledger, derived views, and ending gates. It retrospectively calls v1 a 28-effect bus.

- **Game-design review:** Review: Shard v2 game design. Shard v2 review record, 2026-06-10. Finds the architectural spine sound while identifying unresolved reward, bond, pacing, item, and failure-state questions.

- **Experience evidence plan:** Shard v2 council experience plan. Shard v2 planning record, 2026-06-11. Records an N=1 tuning baseline and calls for a real-player gate before further feature expansion.

- **Current ledger contract:** Shard v2 ledger types. Shard v2 implementation snapshot, 2026-06-20. Implements twelve stable event kinds and typed, append-only history at the reviewed head.

- **Current scene path:** Shard v2 scene engine. Shard v2 implementation snapshot, 2026-06-20. Implements the primary scene-model seam, deterministic checks, accepted events, retry behavior, and ending pressure.

## Continue reading

The reflective long-form account is [From 54 Effects to 12 Events](https://rahilchamola.com/writing/from-54-effects-to-12-events).

---

Creator: Rahil Chamola

Canonical source: https://rahilchamola.com/projects/shard

Preferred citation: Chamola, Rahil. “Shard: project case study.” Curated Randomness, 2026.