An explanation of the depths of the reactivity system we've been using and refining since Ember Octane (ember-source 3.13+).

Given:

And we

1. observe a render,

2. and then click the button,

- and then observe the output count update.

How does it work?

There are a few systems at play for autotracking:

- [tags][^vm-tags]

- [global context][^ember-global-context]

- the environment / delegate

- some [glue code][^ember-renderer] that [configures][^ember-renderer-revalidate] the [timing specifics][^ember-renderer-render-transaction] of when to [render updates][^ember-renderer-render-roots]

- the actual [call to the VM to render][^ember-root-state-render]

[^vm-tags]: https://github.com/glimmerjs/glimmer-vm/blob/d86274816a21c61fbc82059006fe7687ca17dc7e/packages/%40glimmer/validator/lib/validators.ts#L1

[^ember-global-context]: https://github.com/emberjs/ember.js/blob/132b66a768a9cabd461908682ef331f35637d5e9/packages/%40ember/-internals/glimmer/lib/environment.ts#L21

[^ember-renderer]: https://github.com/emberjs/ember.js/blob/132b66a768a9cabd461908682ef331f35637d5e9/packages/%40ember/-internals/glimmer/lib/renderer.ts#L613C1-L614C1

[^ember-renderer-revalidate]: https://github.com/emberjs/ember.js/blob/132b66a768a9cabd461908682ef331f35637d5e9/packages/%40ember/-internals/glimmer/lib/renderer.ts#L626

[^ember-renderer-render-transaction]: https://github.com/emberjs/ember.js/blob/132b66a768a9cabd461908682ef331f35637d5e9/packages/%40ember/-internals/glimmer/lib/renderer.ts#L573

[^ember-renderer-render-roots]: https://github.com/emberjs/ember.js/blob/132b66a768a9cabd461908682ef331f35637d5e9/packages/%40ember/-internals/glimmer/lib/renderer.ts#L524

[^ember-root-state-render]: https://github.com/emberjs/ember.js/blob/132b66a768a9cabd461908682ef331f35637d5e9/packages/%40ember/-internals/glimmer/lib/renderer.ts#L156

- **render**

- call `renderMain()` from glimmer-vm

- this creates a [VM instance and a TemplateIterator](https://github.com/glimmerjs/glimmer-vm/blob/d86274816a21c61fbc82059006fe7687ca17dc7e/packages/%40glimmer/runtime/lib/render.ts#L59)

- tell the [renderer to render](https://github.com/emberjs/ember.js/blob/132b66a768a9cabd461908682ef331f35637d5e9/packages/%40ember/-internals/glimmer/lib/renderer.ts#L165-L168)

1. [executes the VM](https://github.com/glimmerjs/glimmer-vm/blob/d86274816a21c61fbc82059006fe7687ca17dc7e/packages/%40glimmer/runtime/lib/render.ts#L32)

2. iterates over blocks / defers to [_execute](https://github.com/glimmerjs/glimmer-vm/blob/d86274816a21c61fbc82059006fe7687ca17dc7e/packages/%40glimmer/runtime/lib/vm/append.ts#L728)

3. [evaluate opcodes](https://github.com/glimmerjs/glimmer-vm/blob/d86274816a21c61fbc82059006fe7687ca17dc7e/packages/%40glimmer/runtime/lib/vm/append.ts#L770)

4. this brings us to the [low-level VM](https://github.com/glimmerjs/glimmer-vm/blob/main/packages/%40glimmer/runtime/lib/vm/low-level.ts#L167)

5. the low-level VM is the actual VirtualMachine which inteprets all our opcodes -- it iterates until there are no more opcodes

- **read: count**

- access `count`, which `@tracked`'s getter [defers to `trackedData`](https://github.com/emberjs/ember.js/blob/132b66a768a9cabd461908682ef331f35637d5e9/packages/%40ember/-internals/metal/lib/tracked.ts#L155C28-L155C39)

- the [`trackedData`](https://github.com/emberjs/ember.js/blob/132b66a768a9cabd461908682ef331f35637d5e9/packages/%40ember/-internals/metal/lib/tracked.ts#L5) is in `@glimmer/validator` instead of using tags _directly_.

- `trackedData` calls `consumeTag` when [the value is access](https://github.com/glimmerjs/glimmer-vm/blob/main/packages/%40glimmer/validator/lib/tracked-data.ts#L15)

- `consumeTag` adds the tag to the [`CURRENT_TRACKER`](https://github.com/glimmerjs/glimmer-vm/blob/main/packages/%40glimmer/validator/lib/tracking.ts#L116)

- this is so that when any `{{ }}` regions of a template "detect" a dirty tag, they can individually re-render

- [valueForRef](https://github.com/glimmerjs/glimmer-vm/blob/main/packages/%40glimmer/reference/lib/reference.ts#L155)

- called by _many_ opcode handlers in the VM, in this case: [this APPEND_OPCODE](https://github.com/glimmerjs/glimmer-vm/blob/main/packages/%40glimmer/runtime/lib/compiled/opcodes/content.ts#L88)

- [track](https://github.com/glimmerjs/glimmer-vm/blob/main/packages/%40glimmer/validator/lib/tracking.ts#L232)

- calls [beginTrackFrame](https://github.com/glimmerjs/glimmer-vm/blob/d86274816a21c61fbc82059006fe7687ca17dc7e/packages/%40glimmer/validator/lib/tracking.ts#L58) and the corresponding `endTrackFrame()`

- **render a button with modifier**

- for demonstration purposes, this phase is skipped in this explanation, as this document is more about auto-tracking, and less so about how elements and event listeners get wired up

- `increment()`

- **read: count**

- reading is part of `variable++` behavior

- **set: count**

- we dirty the tag [via `@tracked`'s setter](https://github.com/emberjs/ember.js/blob/132b66a768a9cabd461908682ef331f35637d5e9/packages/%40ember/-internals/metal/lib/tracked.ts#L171)

- `scheduleRevalidate()` is called by `dirtyTag()`, which then defers to ember to call these things and interacts with the scheduler (we go back to step 1):

- **env.begin**

- **env.rerender**

- **read: count**

- **env.commit**

the output, `count` is rendered as `1`

[JSBin, here](https://jsbin.com/mobupuh/edit?html,output)

1. [Tag Composition](./tag-composition.md): The formal composition semantics of Glimmer's tag-based

validation system.

2. [The Fundamental Laws of Reactivity](./laws.md): A definition of Glimmer's reliable and

consistent reactive programming model, and the rules that reactive abstractions must

satisfy in order to safely support this model.

3. [System Phases](./system-phases.md): A description of the phases of the Glimmer execution model:

_action_, _render_, and _idle_, and how the exeuction model supported batched _UI_ updates while

maintaining a _coherent_ data model.

4. [Reactive Abstractions](./reactive-abstractions.md): A description of the implementation of

a number of reactive abstractions, and how they satisfy the laws of reactivity.

5. [Autotracked Rendering](./autotracked-rendering.md): An overview of the

details of how rendering and autotracking interplay.

This directory also contains pseudocode for the foundation of a reactive system that satisfies these

requirements, and uses them to demonstrate the implementation of the reactive abstractions.

- [`tags.ts`](./pseudocode/tags.ts): A simple implementation of the tag-based validation system,

including an interface for a runtime that supports tag consumptions and tracking frames.

- [`primitives.ts`](./pseudocode/primitives.ts): Implementation of:

- `Snapshot`, which captures a value at a specific revision with its tag validator.

- `PrimitiveCell` and `PrimitiveCache`, which implement a primitive root storage and a primitive

cached computation, both of which support law-abiding snapshots.

- [`composition.ts`](./pseudocode/composition.ts): Implementations of the higher-level reactive

constructs described in [Reactive Abstractions](./reactive-abstractions.md) in terms of the

reactive primitives.

From the perspective of a Glimmer user, this axiom enables writing reactive code using standard

JavaScript functions and getters that automatically reflect the current state of UI inputs.

**Glimmer users write UI code as straightforward rendering functions**, yet the system behaves _as

if_ these functions re-execute completely whenever any reactive value changes.

- **Root Reactive State**: An atomic reactive value that can be updated directly. It is represented

by a single [value tag](./concepts.md#value-tag). You can create a single piece of root state

explicitly using the `cell` API, but containers from `tracked-builtins` and the storage created by

the `@tracked` decorator are also root reactive state.

- **Formula**: A reactive computation that depends on a number of reactive values. A formula's

revision is the most recent revision of any of the members used during the last computation (as a

[combined tag](./concepts.md#combined-tag)). A

formula will _always_ recompute its output if the revision of any of its members is advanced.

- **Snapshot**: A _snapshot_ of a reactive abstraction is its _current value_ at a specific

revision. The snapshot <a id="invalidate"></a> _invalidates_ when the abstraction's tag has a more

recent revision. _A reactive abstraction is said to _invalidate_ when any previous snapshots would

become invalid._

In order to satisfy the _Fundamental Axiom of Reactivity_, all reactive abstractions must adhere to these six laws:

1. **Dependency Tracking**: A reactive abstraction **must** [invalidate](#invalidate) when any

reactive values used in its _last computation_ have changed. _The revision of the tag associated

with the reactive abstraction <u>must</u> advance to match the revision of its most recently

updated member._

2. **Value Coherence**: A reactive abstraction **must never** return a cached _value_ from a

revision older than its current revision. _After a root state update, any dependent reactive

abstractions must recompute their value when next snapshotted._

3. **Transactional Consistency**: During a single rendering transaction, a reactive abstraction

**must** return the same value and revision for all snapshots taken within that transaction.

4. **Snapshot Immutability**: The act of snapshotting a reactive abstraction **must not**

advance the reactive timeline. _Recursive snapshotting (akin to functional composition) naturally

involves tag consumption, yet remains consistent with this requirement as immutability applies

recursively to each snapshot operation._

5. **Defined Granularity**: A reactive abstraction **must** define a contract specifying its

_invalidation granularity_, and **must not** invalidate more frequently than this contract

permits. When a reactive abstraction allows value mutations, it **must** specify its equivalence

comparison method. When a new value is equivalent to the previous value, the abstraction **must

not** invalidate.

All reactive abstractions—including built-in mechanisms like `@tracked` and `createCache`, existing

libraries such as `tracked-toolbox` and `tracked-builtins`, and new primitives like `cell`—must

satisfy these six laws to maintain the Fundamental Axiom of Reactivity when these abstractions are

composed together.

import { PrimitiveCache, PrimitiveCell, type Status } from './primitives';

import { runtime, MutableTag, type Tag } from './tags';

export class LocalCopy<T> {

#upstream: PrimitiveCache<T>;

#local: PrimitiveCell<T>;

constructor(compute: () => T) {

this.#upstream = new PrimitiveCache(compute);

this.#local = new PrimitiveCell();

}

/**

read(): T {

return mostRecent(this.#upstream.snapshot(), this.#local.unsafeSnapshot()).value;

}

/**

write(value: T): void {

this.#local.write(value);

}

function mostRecent<S extends [Status<unknown>, ...Status<unknown>[]]>(...statuses: S): S[number] {

const [first, ...rest] = statuses;

runtime.consume(first.tag);

return rest.reduce((latest, status) => {

runtime.consume(latest.tag);

return status.tag.revision > latest.tag.revision ? status : latest;

}, first);

export function tracked<V, This extends object>(

_value: ClassAccessorDecoratorTarget<This, V>,

context: ClassAccessorDecoratorContext<This, V>

): ClassAccessorDecoratorResult<This, V> {

// When the field is initialized, initialize a mutable tag to represent the root storage.

context.addInitializer(function (this: This) {

MutableTag.init(this, context.name);

});

return {

get(this: This): V {

// When the field is accessed, consume the tag to track the read, and return the underlying

// value stored in the field.

const tag = MutableTag.get(this, context.name);

tag.consume();

return context.access.get(this);

},

set(this: This, value: V): void {

// When the field is written, update the tag to track the write, and update the underlying

// value stored in the field.

const tag = MutableTag.get(this, context.name);

context.access.set(this, value);

tag.update();

},

};

const COMPUTE = new WeakMap<Cache<unknown>, () => unknown>();

declare const FN: unique symbol;

type FN = typeof FN;

type Cache<T> = {

[FN]: () => T;

export function createCache<T>(fn: () => T): Cache<T> {

const cache = {} as Cache<T>;

let last = undefined as { value: T; tag: Tag; revision: number } | undefined;

COMPUTE.set(cache, () => {

if (last && last.revision >= last.tag.revision) {

runtime.consume(last.tag);

return last.value;

}

runtime.begin();

try {

const result = fn();

const tag = runtime.commit();

last = { value: result, tag, revision: runtime.current() };

runtime.consume(tag);

return result;

} catch {

last = undefined;

}

});

return cache;

export function getCache<T>(cache: Cache<T>): T {

const fn = COMPUTE.get(cache);

if (!fn) {

throw new Error('You must only call `getCache` with the return value of `createCache`');

}

return fn() as T;