npm - @sovereignbase/sequencer - Versions diffs - 1.0.0 → 1.0.1 - Mend

@sovereignbase/sequencer 1.0.0 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (11) hide show

package/INTERNALS.md CHANGED Viewed

@@ -1,50 +1,34 @@
-# How Sequencer works
+# How sequencer works
-Sequencer gives applications an ordinary indexed sequence while internally maintaining a stable distributed history.
+Sequencer keeps an ordered sequence synchronized between replicas.
-An application sees something simple:
+Applications see a normal indexed sequence:
 ```text
 A B C D
 ```
-and edits it using positions:
+with positions:
 ```text
-insert at 2
-remove 1..3
-replace 4..6
+0 1 2 3
 ```
-Those positions are useful locally, but they cannot be replicated directly.
+Internally Sequencer cannot use those positions to describe replicated edits.
-Two replicas may edit concurrently. By the time an operation reaches another replica, content may have been inserted or removed before the original position. Position `5` on one replica may therefore refer to something completely different on another.
-Sequencer solves this by translating every local edit from a temporary visible position into a stable relationship with existing history.
-The basic model is:
+If another Frame is inserted before `B`:
 ```text
-visible Projection
-        ↓
-historical logical point
-        ↓
-canonical Insertion
-        ↓
-deterministic Structural Order
-        ↓
-visible Projection
+A X B C D
 ```
-Replicas do not need to agree on temporary positions, network arrival order, runtime fragmentation, or local indexes.
+`B` moves from position `1` to position `2`.
-They only need to eventually receive the same canonical history.
+Instead, when an edit is made, Sequencer finds the existing history around that position and records the edit relative to it.
----
+## Projection and Structural Order
-## Projection is the visible sequence
-The **Projection** is what the application sees.
+The **Projection** is the sequence the application currently sees.
 For example:
@@ -52,15 +36,13 @@ For example:
 A B C D
 ```
-contains four visible values, called **Frames**:
+has four visible Frames:
 ```text
 A   B   C   D
 0   1   2   3
 ```
-Applications read and edit these visible positions.
 Insertion positions are boundaries between Frames:
 ```text
@@ -68,80 +50,37 @@ Insertion positions are boundaries between Frames:
 0   1   2   3   4
 ```
-This distinction is important.
-A Frame position identifies visible content.
-A boundary identifies a place where new history can be attached.
-Projection positions are deliberately temporary. They describe the current visible result, not the permanent identity of anything inside it.
----
-## History must use stable coordinates
-Suppose two replicas begin with:
-```text
-A B
-```
-Replica 1 inserts:
+Behind the Projection is **Structural Order**.
-```text
-X
-```
+Structural Order contains the Insertions that produced the sequence, including history that may no longer be visible.
-between them:
+A simple sequence might start as:
 ```text
-A X B
-```
-At the same time, Replica 2 inserts:
+Structural Order
-```text
-Y
-```
+[A B C D]
-at the same visible position:
+Projection
-```text
-A Y B
+A B C D
 ```
-Both operations were authored at position `1`.
-If Sequencer replicated only:
+After `B C` are removed, the Projection becomes:
 ```text
-insert X at 1
-insert Y at 1
+A D
 ```
-the final result could depend on which packet happened to arrive first.
-Instead, both edits are translated into a relationship with the same historical boundary between `A` and `B`.
-That boundary remains meaningful even after the visible sequence changes.
+but Structural Order still contains the original positive Insertion and the history describing the removal.
-Sequencer can then deterministically order the two competing Insertions.
+More history can later attach to those original coordinates, so hidden history may remain useful long after its Frames disappear from the Projection.
----
+## Insertions
-# Canonical Insertions
+History is made of **Insertions**.
-The fundamental replicated unit in Sequencer is an **Insertion**.
-Conceptually, every Insertion contains:
-```text
-where it belongs
-+
-what history it introduces
-```
-Its canonical coordinates are:
+An Insertion has six coordinates:
 ```text
 anchorSession
@@ -153,399 +92,325 @@ insertionStart
 insertionDiff
 ```
-These six values describe two independent things.
-The anchor:
+The first three describe where the Insertion belongs:
 ```text
 (anchorSession, anchorStart, anchorDiff)
 ```
-describes where the Insertion belongs.
-The identity:
+The next two identify the Insertion:
 ```text
 (insertionSession, insertionStart)
 ```
-describes which Insertion it is.
+and `insertionDiff` describes its original Frame length and whether it adds or removes Frames.
-The effect:
+A positive Insertion adds Frames:
 ```text
-insertionDiff
+insertionDiff = 4
 ```
-describes how many original Frames it contributes.
+A reducing Insertion masks Frames:
-A positive Insertion introduces Frames.
+```text
+insertionDiff = -4
+```
-A negative Insertion represents removal.
+Positive Insertions can also carry **Footage**, which contains the actual values.
----
+Sequencer orders the Insertion. Footage is what eventually appears in the Projection.
-## Insertion identity never depends on location
+## Frames and logical points
-A canonical Insertion is identified by:
+Suppose one Insertion contains:
 ```text
-(insertionSession, insertionStart)
+A B C
 ```
-Its identity does not include its anchor.
-This means:
+It has three Frames:
 ```text
-identity
+A   B   C
+0   1   2
 ```
-and:
+and four logical points:
 ```text
-position in history
+| A | B | C |
+0   1   2   3
 ```
-are separate concepts.
-That separation is useful for several reasons.
-The same operation can be recognized after retransmission.
-Fragments of one Insertion still belong to the same canonical identity.
-An Insertion can be found independently from whichever Strip currently represents its anchor.
-And duplicate delivery does not create duplicate visible content.
----
-# Logical time
-Every sequencing Session owns its own logical coordinate space.
-A newly authored Insertion receives a start position inside that Session.
+An anchor points to one of these boundaries.
 For example:
 ```text
-Session 12
-Insertion A starts at 0
-Insertion B starts at 6
-Insertion C starts at 11
+anchorDiff = 2
 ```
-These are not wall-clock timestamps.
-They are logical coordinates used only to identify history.
-A canonical Insertion normally reserves both:
+refers to:
 ```text
-its Frame extent
-+
-a following logical boundary
+A B | C
 ```
-before the next independent Insertion in the same Session.
-That following boundary gives later history a stable point to reference.
----
-## Frames and logical points are different
+inside that original Insertion.
-Consider an Insertion containing:
+If later edits move `C` somewhere else in the Projection, this point is still point `2` of the same original Insertion.
-```text
-A B C
-```
+## Anchoring an edit
-It contains three Frames:
+Suppose the Projection contains:
 ```text
-0 1 2
+Hello world
 ```
-but four logical boundary points:
+and `big ` is inserted here:
 ```text
-| A | B | C |
-0   1   2   3
+Hello | world
 ```
-An anchor refers to one of these logical points.
+Sequencer first finds which original Insertion owns that boundary.
-For example:
+If the boundary is point `6` of an Insertion identified by:
 ```text
-anchorDiff = 2
+(session 4, start 20)
 ```
-means:
+the new Insertion can anchor to:
 ```text
-A B | C
+anchorSession = 4
+anchorStart   = 20
+anchorDiff    = 6
 ```
-inside that specific historical Insertion.
-It does **not** mean:
+Another replica might currently see:
 ```text
-Projection position 2
+Well, Hello world
 ```
-That distinction is one of the most important ideas in Sequencer.
+The same anchor still refers to the point after `Hello ` in the original Insertion.
-Visible positions move.
+The Projection position is different, but the relationship is the same.
-Historical logical points do not.
+## Insertion identity
----
-# From a local edit to canonical history
-Suppose the current Projection is:
+An Insertion is identified by:
 ```text
-Hello world
+(insertionSession, insertionStart)
 ```
-and the application inserts:
+The anchor is not part of its identity.
-```text
-big
-```
+If the same Insertion arrives twice, both copies have the same identity.
-here:
+Sequencer can keep the first and ignore the duplicate instead of inserting the same content twice.
-```text
-Hello | world
-```
+Fragments of an Insertion also keep this identity. Splitting an Insertion at runtime does not create new replicated history.
-The application supplies only the visible boundary.
+## Sessions
-Sequencer resolves that boundary to the historical Insertion that owns it.
+Insertions are authored inside **Sessions**.
-It then records the edit relative to that original Insertion:
+A Session has its own logical time.
-```text
-specific historical Insertion
-+
-specific logical point inside it
-```
+Suppose a Session creates a three-Frame Insertion starting at `0`.
-The operation therefore means:
+Its Frame coordinates occupy:
 ```text
-insert here in history
+0 1 2
 ```
-rather than:
+and its endpoint is:
 ```text
-insert at visible index 6
+3
 ```
-Another replica may have more visible content before that point.
+A new independent Insertion normally starts after another reserved logical point:
-The numeric Projection position may differ.
+```text
+0 1 2 | 3
+          ↑
+       boundary
-The historical relationship does not.
+next start = 4
+```
----
+The gap gives the previous Insertion its own endpoint without making that endpoint the identity of the next independent Insertion.
-# Structural Order
+Positive and reducing history use separate Sessions.
-Canonical history must eventually form one deterministic order.
+Session identifiers are also separate from Actor identifiers. Two replicas belonging to the same Actor can author their own Sessions without sharing one sequencing clock.
-Sequencer calls this **Structural Order**.
+## Structural Order
-Structural Order contains everything required to explain the visible sequence, including history that may no longer itself be visible.
+Every materialized Insertion is placed into one Structural Order.
-It may contain:
+Suppose the original history is:
 ```text
-positive Insertions
-removal history
-fragments
-concurrent siblings
-causal descendants
-hidden historical boundaries
+A B
 ```
-The Projection is derived from this structure.
-Conceptually:
+and a new Insertion anchors between them:
 ```text
-Structural Order
-        ↓
-surviving positive Frames
-        ↓
-Projection
+A | B
 ```
-Structural Order is therefore richer than the visible sequence.
-The Projection answers:
+Structural Order can now represent:
 ```text
-what is visible now?
+A X B
 ```
-Structural Order answers:
-```text
-what historical relationships produced that result?
-```
----
-# Concurrent Insertions
-Two Insertions directly compete when they use exactly the same canonical anchor.
-For example, both of these may attach to:
+If another replica concurrently inserts `Y` at the same anchor, both new Insertions describe the same historical point:
 ```text
 A | B
+  X
+  Y
 ```
-independently:
+They must get the same order on every replica even when they arrive in different orders.
-```text
-X
-Y
-```
+Sequencer orders competing Insertions from the anchor outward by:
-The order between them cannot depend on which replica received which packet first.
+1. positive Insertions before reducing Insertions;
+2. greater Session first;
+3. within the same Session, greater start first.
-Sequencer therefore defines a deterministic competitor ordering.
-Closer to the shared anchor:
-1. positive Insertions come before reducing Insertions;
-2. within the same sign, larger Session identifiers come first;
-3. within the same Session, larger start coordinates come first.
-Every replica can calculate this from the canonical history alone.
-So one replica may receive:
+So receiving:
 ```text
 X
 Y
 ```
-while another receives:
+or:
 ```text
 Y
 X
 ```
-but both eventually construct the same Structural Order.
----
+produces the same Structural Order once both are known.
-# Causal subtrees stay together
+## Causal subtrees
-A concurrent competitor may later receive children of its own.
+An Insertion can have more history attached to it.
-Those children form its **causal subtree**.
+Suppose two replicas start from an empty sequence.
-Consider two replicas that independently create root content:
+One creates:
 ```text
-Document A
+Project notes
 ```
-and:
+and continues editing it.
+The other independently creates:
 ```text
-Document B
+Shopping list
 ```
-Before synchronizing, both continue editing their own document.
+and continues editing that.
-The two roots compete at the same virtual root anchor.
+The two initial Insertions compete at the root.
-Sequencer deterministically decides which root comes first.
-But the descendants of each root must remain with that root.
-The final Structural Order may be:
+Their later edits are descendants of those roots:
 ```text
-[Document A and its descendants]
+Project notes
+├─ child
+└─ child
-[Document B and its descendants]
+Shopping list
+├─ child
+└─ child
 ```
-or the reverse.
-It must not become:
+When the roots are ordered, their descendants stay with them:
 ```text
-part of A
-part of B
-rest of A
-rest of B
+[Project notes subtree]
+[Shopping list subtree]
 ```
-Competitor ordering therefore works on causal subtrees, not merely isolated nodes.
-This is what lets independently developed branches of history remain coherent when they meet.
+rather than becoming interleaved:
----
+```text
+part of Project notes
+part of Shopping list
+rest of Project notes
+rest of Shopping list
+```
-# History can arrive in any causal order
+When a competitor is inserted into Structural Order, its place is determined relative to the complete subtree of the competitors already there.
-Distributed delivery may be reordered.
+## History can arrive before its parent
-Suppose one replica first creates:
+Suppose one replica creates:
 ```text
 Hello
 ```
-and later extends it into:
+and then inserts:
 ```text
-Hello world
+ world
 ```
-Another replica may receive the history for:
+after it.
+The second Insertion anchors to the first.
+Another replica may receive:
 ```text
  world
 ```
-before it receives the history containing:
+before:
 ```text
 Hello
 ```
-The child relationship is perfectly valid, but its parent does not yet exist locally.
+There is not yet anything local that can resolve the anchor.
-Sequencer keeps that history unresolved until the required canonical parent becomes available.
+The Insertion waits.
-When the missing parent later arrives, the relationship becomes resolvable.
+When `Hello` arrives, its identity becomes available and the waiting Insertion can be placed:
-No retransmission or special causal network ordering is required.
+```text
+Hello world
+```
-The same principle applies when the parent exists but has not yet grown far enough to contain the logical point referenced by the incoming history.
+The same thing can happen when the parent exists but has not yet grown far enough to contain the referenced logical point.
----
+The relationship itself does not change while it waits.
-# Author-time relationships survive receiver-time differences
+## Author-time relationships
-Consider an author producing:
+This allows edits to describe the sequence as it existed when they were authored without requiring another replica to pass through the same intermediate states.
+For example, one replica may produce:
 ```text
 world
@@ -556,7 +421,7 @@ Now, Well, actually Hello world
 Okay, Now, Well, actually Hello world
 ```
-Another replica might receive the individual pieces in a very different order:
+Another replica might receive the Insertions in this order:
 ```text
 world
@@ -567,128 +432,66 @@ Well
 Okay
 ```
-The operations do not depend on the receiver seeing the same intermediate Projection that the author saw.
-Each operation describes where it belonged relative to existing canonical history at author time.
+`actually` is still attached to the historical Insertion it followed when it was authored.
-Once all necessary relationships are available, they reconstruct:
+Once the required history has arrived, the relationships can be resolved into:
 ```text
 Okay, Now, Well, actually Hello world
 ```
-Sequencer therefore preserves:
+## Strips
-```text
-author-time relationships
-```
+An Insertion does not always stay in one piece inside a running Projection.
-rather than:
-```text
-author-time numeric indexes
-```
----
-# Canonical history and runtime fragmentation
-A canonical Insertion is a logical piece of history.
-It does not need to remain one physical runtime object forever.
-Suppose one Insertion originally contains:
+Suppose an original Insertion contains:
 ```text
 A B C D
 ```
-Later edits may require the runtime to split it:
+An edit at the middle may split its runtime representation into:
 ```text
 [A B] [C D]
 ```
-These pieces are called **Strips**.
+These pieces are **Strips**.
-The important point is that they are not new canonical Insertions.
+Both Strips still belong to the same original Insertion.
-Both still belong to the same original history:
+The original coordinate space is still:
 ```text
-same anchor
-same insertion identity
-same original coordinate space
-```
-They merely represent different portions of it at runtime.
-Conceptually:
-```text
-canonical Insertion
 | A | B | C | D |
 0   1   2   3   4
-         ↓
-runtime materialization
-[A B]       [C D]
-```
-The logical points remain:
-```text
-0 1 2 3 4
 ```
-even if the current physical representation is split around point `2`.
+The left Strip represents one part of that space and the right Strip represents another.
-This allows old operations to continue referring to historical locations after arbitrary later fragmentation.
+An operation authored earlier against point `3` can still find point `3` even though the original Insertion is no longer represented by one Strip.
----
+Different replicas can also have different fragmentation.
-# Canonical coordinates survive fragmentation
-This separation between canonical identity and runtime representation is essential.
-A replica may represent one Insertion as:
+One might currently have:
 ```text
 [A B C D]
 ```
-while another currently represents the same canonical Insertion as:
+while another has:
 ```text
 [A] [B C] [D]
 ```
-The two replicas still agree on:
+They still agree on the original Insertion and its coordinates.
-```text
-which Insertion it is
-```
+## Extending an Insertion
-and:
-```text
-which original logical point an anchor refers to
-```
+Consecutive editing often continues the Insertion that was just created.
-They do not need identical runtime layouts.
-The receiver resolves canonical coordinates through whatever fragmentation exists locally.
-Runtime fragmentation is therefore invisible to replication.
----
-# Consecutive editing can extend history
-Without any coalescing, typing:
+Typing:
 ```text
 H
@@ -698,13 +501,9 @@ Hell
 Hello
 ```
-could create one canonical Insertion for every character.
-That would preserve correctness, but history would grow unnecessarily quickly.
+does not need five unrelated canonical Insertions.
-Sequencer can instead extend a recent positive Insertion when the new edit is a genuine continuation of that same history.
-Conceptually:
+When the new content is a clean continuation of the latest local positive Insertion, its original extent can grow:
 ```text
 H
@@ -718,35 +517,19 @@ Hell
 Hello
 ```
-may remain one growing canonical Insertion.
-The key requirement is that extending it must not change previously established structural relationships.
-If history has already attached to the old endpoint in a way that requires that boundary to remain distinct, a new independent Insertion is created instead.
-If the canonical Insertion has fragmented at runtime, a valid extension can still become another fragment of the same grown canonical identity.
+The continuation starts at the old endpoint of the same Session, so another replica can recognize it as an extension of the existing Insertion.
-Extension is therefore a history-growth optimization that preserves the same underlying model.
+This is only done while the old endpoint can safely grow.
----
+If other history already depends on that endpoint in a way that would change its ordering, the new content becomes a normal separate Insertion instead.
-# Removal is not deletion of history
+An Insertion can also be extended after it has fragmented. The new suffix may need its own Strip, but it still belongs to the same canonical Insertion.
-Removing visible content does not immediately erase its original Insertion.
+## Removal
-Instead, removal is represented as new history.
+Removal is represented by reducing Insertions.
-A removal is a reducing Insertion:
-```text
-insertionDiff < 0
-```
-which targets original Frames belonging to a positive Insertion.
-This is best understood as **masking**.
-Suppose the original content is:
+Suppose one positive Insertion contains:
 ```text
 A B C D
@@ -754,27 +537,27 @@ A B C D
 and `B C` are removed.
-The historical positive Insertion still exists.
-A reducing Insertion records:
+The removal anchors to the original positive Insertion and covers those original Frames:
 ```text
-mask original Frames B and C
+original
+A B C D
+  └─┬─┘
+  removed
 ```
-The Projection then contains:
+The Projection becomes:
 ```text
 A D
 ```
-but Structural Order still knows what happened.
+The original coordinates still exist in Structural Order.
----
+This becomes especially useful when insertion and removal happen concurrently.
-# Why removal must target original Frames
-Consider two replicas starting with:
+Suppose both replicas start with:
 ```text
 The old house
@@ -786,135 +569,103 @@ Replica A removes:
 old
 ```
-while Replica B concurrently inserts:
+and sees:
 ```text
-small
+The house
 ```
-after it:
+At the same time Replica B inserts:
 ```text
-The old small house
+small
 ```
-Replica A never observed:
+after `old `:
 ```text
-small
+The old small house
 ```
-Its removal should therefore not remove that concurrent content.
+The removal authored by A refers to the original Frames of `old `.
-Because removal targets original Frames rather than a mutable visible interval, it masks only:
+It never referred to `small ` because those Frames did not exist in A's history.
-```text
-old
-```
-After synchronization the result becomes:
+After synchronization:
 ```text
 The small house
 ```
-regardless of delivery order.
+The concurrent insertion survives.
-This is one of the core consequences of using historical coordinates rather than Projection indexes.
+## A removal can cross several Insertions
----
+A visible range can contain Frames from several original Insertions.
-# A visible removal may cross several histories
-What looks like one contiguous visible range may internally contain Frames from several canonical Insertions.
-For example:
+For example, the Projection:
 ```text
 Hello world
 ```
-might structurally contain:
+might have been built from:
 ```text
-[Hello]
-[ ]
-[world]
+[Hello] [ ] [world]
 ```
-from three different historical Insertions.
 Removing:
 ```text
 lo wo
 ```
-therefore cannot be represented as one blind operation against a Projection range.
-Sequencer expresses the removal against the actual original Insertions whose Frames are being consumed.
-Each reducing Insertion targets only Frames belonging to its own historical parent.
+crosses all three.
-This prevents removals from accidentally claiming content they never observed.
+Sequencer describes the removal against the original Frames of each Insertion it crosses.
----
+The visible edit is one range, but its historical description can contain several reducing Insertions.
-# Removal can also fragment
+## Removal fragments
-A single canonical removal may encounter an original Insertion that has already fragmented.
+A reducing Insertion can also become fragmented.
-Suppose original history contains:
+Suppose an original positive Insertion contains:
 ```text
 A B C D E F
 ```
-but the current runtime representation is:
+and its current structural representation has already become:
 ```text
 [A B] [C D] [E F]
 ```
-A removal of:
+A removal covering:
 ```text
 B C D E
 ```
-may need to materialize across several runtime regions.
+may need mask fragments at several places in Structural Order.
-Those pieces are still one canonical removal.
+Those mask Strips still belong to one canonical reducing Insertion.
-They do not become independent replicated operations merely because the runtime needed several Strips to express their effect.
+Its identity and original target coordinates do not change.
-Again:
+## Overlapping removals
-```text
-canonical history
-```
+Two replicas can remove some of the same original Frames.
-and:
-```text
-runtime representation
-```
-remain separate.
----
-# Overlapping removals
-Concurrent replicas may independently remove overlapping Frames.
-For example, from:
+Starting from:
 ```text
 the brown fox jumps
 ```
-one replica removes:
+one replica might remove:
 ```text
 brown fox
@@ -926,605 +677,221 @@ while another removes:
 fox jumps
 ```
-Both removals refer to original Frames.
-The Frames belonging to:
+Both target the original Frames of `fox`.
-```text
-fox
-```
+When the second removal is integrated, those Frames may already be masked.
-were targeted twice.
+They cannot reduce the Projection again.
-They must still disappear only once from the Projection.
+The reducing Insertion still describes the range it originally targeted, while its runtime effect is limited to original Frames that remain available for it to consume.
-A reducing Insertion therefore retains its canonical authored meaning while its current runtime effect is resolved against Frames that remain available to consume.
+This lets overlapping removals arrive in either order without changing the result.
-This guarantees:
-```text
-one original Frame cannot reduce the Projection twice
-```
+## Replacement
-Delivery order cannot cause repeated subtraction or make deleted content reappear.
+Replacement is a removal followed by a positive Insertion.
----
-# Replacement is composition
-Replacement does not require its own structural concept.
-Replacing:
+Changing:
 ```text
 Draft
 ```
-with:
+to:
 ```text
 Final
 ```
-is simply:
-```text
-remove Draft
-insert Final
-```
-The important part is the relationship between those two operations.
-The new content is anchored against the history that exists after the removal relationship has been established.
-This keeps replacement semantics consistent with ordinary insertion and removal instead of introducing another independent ordering model.
----
-# Visible content and historical content are deliberately different
-After enough editing, Structural Order may contain much more history than the Projection shows.
-For example:
-```text
-Structural Order
-[A B C]
-[mask B]
-[X]
-[mask C]
-[Y]
-```
-could produce a Projection such as:
-```text
-A X Y
-```
-The hidden history is not accidental garbage.
-It may still be required to understand:
-```text
-future delayed operations
-historical anchor points
-concurrent relationships
-removal ownership
-ordering of descendants
-```
-Sequencer therefore cannot simply delete every hidden node as soon as it stops being visible.
----
-# Replication transports canonical history
-Replicas exchange canonical Insertions and acknowledgement information.
-The transport itself is not part of the sequencing model.
-History may be delivered:
-```text
-immediately
-later
-out of order
-more than once
-through a central server
-peer to peer
-after being persisted
-```
-None of these should affect the eventual ordering.
-The important property is that the same canonical history eventually reaches the replicas that need it.
----
-# Duplicate delivery is harmless
-Because canonical Insertions have stable identities, receiving the same history multiple times does not duplicate its visible effect.
-This allows replication systems to favor reliability over exactly-once transport.
-A sender can retransmit uncertain history.
-A relay can replay stored history.
-A reconnecting replica can receive data it already has.
-Sequencer recognizes the canonical identity and keeps the resulting history idempotent.
----
-# Actors and Sessions have different roles
-A **Session** identifies authored sequencing history.
-An **Actor** participates in acknowledgement of removal history.
-These concepts are intentionally separate.
-One Actor may have several independent Sessions.
-Different replicas belonging to the same logical Actor can therefore create history without sharing one mutable sequencing clock.
-Session identities answer:
-```text
-who authored this canonical history stream?
-```
-Actor identities answer:
-```text
-whose acknowledgement is required before old removal history can be forgotten?
-```
----
-# Why acknowledgements are needed
-Suppose Replica A removes some content.
-Replica B is currently offline.
-Replica B may still contain unsent history anchored to the content that A removed.
-If A permanently discarded every trace of that historical content immediately, B's delayed operation could later refer to a point that no longer exists anywhere in A's retained state.
-Sequencer therefore separates:
-```text
-content is no longer visible
-```
-from:
-```text
-history is safe to forget
-```
-Those are not the same event.
----
-# Removal frontiers
-Actors acknowledge received prefixes of removal Sessions.
-Conceptually an acknowledgement says:
-```text
-Actor A has observed this removal Session
-through logical point N
-```
-A frontier summarizes a whole contiguous prefix rather than listing every individual removal.
-This keeps acknowledgement state small while still allowing Sequencer to determine which removal history is globally known among the active Actors.
----
-# Compaction
-Once all active Actors agree on a removal frontier, the acknowledged removal history becomes eligible for compaction.
-Compaction does not simply delete mask nodes.
-It constructs an equivalent retained history in which obsolete removed Frames and the historical machinery surrounding them can be omitted.
-This may involve:
-```text
-removing acknowledged masks
-removing Footage that can no longer reappear
-shortening positive Insertions
-adjusting surviving mask coordinates
-collapsing obsolete logical regions
-re-anchoring surviving history
-```
-The required invariant is simple:
-```text
-Projection before compaction
-==
-Projection reconstructed from compacted history
-```
-But preserving that invariant under future editing is the harder part.
-The compacted history must not only look the same now.
-It must also preserve the ordering relationships that remain relevant later.
----
-# Compaction can collapse historical space
-Consider surviving children originally attached to two different logical points:
-```text
-point 1
-   ↓
-removed historical region
-   ↓
-point 2
-```
-After the region between them becomes safe to forget, both historical points may collapse onto the same retained boundary.
-At that point the original geometric distinction no longer exists.
-But the children may already have a resolved order.
-Compaction must preserve that order.
-Sequencer can therefore re-anchor surviving positive history according to its already resolved retained Structural Order.
-In other words, once obsolete history is discarded:
+first masks the Frames of:
 ```text
-resolved order
-```
-can become more important than:
-```text
-the exact historical path that originally produced it
-```
-This is what lets retained state become smaller without reopening old ordering decisions.
----
-# Compaction does not rewrite live history
-Compaction operates on retained state.
-A live Projection does not need to restructure itself every time a snapshot is produced.
-Instead:
-```text
-live Structural Order
-        ↓
-derive equivalent compacted history
-        ↓
-persist / transfer snapshot
-```
-A later Projection can hydrate from that compacted history and produce the same visible state and compatible future ordering.
-This keeps persistence optimization separate from the current editing runtime.
----
-# Actor retirement
-A permanently gone Actor would otherwise block removal compaction forever.
-Sequencer therefore allows an Actor to be retired from future acknowledgement consensus.
-Retirement means:
-```text
-this Actor is no longer expected to acknowledge future compaction
+Draft
 ```
-It does not mean:
+and then anchors:
 ```text
-delete history authored by this Actor
+Final
 ```
-Those are unrelated concepts.
+into the resulting history.
-Retirement is an application-level decision because Sequencer cannot know whether a disconnected replica is temporarily offline or permanently abandoned.
+Both parts use the same insertion and removal rules as every other edit.
----
+## Actors and acknowledgements
-# Persistence retains history, not runtime state
+Removal history cannot always be discarded when it disappears from the Projection.
-A persisted Sequence contains the history needed to reconstruct the Projection.
+Suppose one replica removes some Frames while another replica is offline.
-It does not need to persist every runtime optimization.
+The offline replica may still have unsent history anchored to those Frames.
-For example, persistence needs the equivalent of:
+The removed Frames must remain addressable until that old history no longer needs to be supported.
-```text
-canonical Insertions
-retained acknowledgement state
-positive Footage
-```
+Actors report how far they have observed each reducing Session.
-It does not need to preserve things such as:
+For example:
 ```text
-current fragmentation layout
-temporary traversal indexes
-recent lookup positions
-allocation addresses
-```
-Those can be reconstructed.
-The persistence boundary therefore follows the same conceptual separation as replication:
+Actor 3
-```text
-stable history is durable
-runtime materialization is disposable
+removal Session 17
+observed through logical time 42
 ```
----
+The reported point is a **frontier**.
-# Hydration reconstructs an equivalent Projection
+A single frontier summarizes a received prefix of a Session rather than acknowledging every reducing Insertion separately.
-When retained history is loaded again, Sequencer reconstructs the structural relationships encoded by that history and derives the visible Projection.
+## Compaction
-The important requirement is not that the new runtime representation be byte-for-byte identical to the previous one.
+When all active Actors agree on the same frontier for a reducing Session, the acknowledged part can be removed from future retained Sequences.
-It only needs to reconstruct the same meaningful state:
+Suppose history contains:
 ```text
-same visible content
-same retained canonical relationships
-same deterministic future ordering
+positive Frames
+removal mask
+surviving descendants
 ```
-Runtime Strip boundaries or indexes may differ.
-They are not part of the distributed identity of the sequence.
----
-# The same history can have different runtime shapes
+and every active Actor has seen the removal.
-This is a useful general principle.
+A new retained Sequence no longer needs to preserve all of the machinery that represented that deletion.
-Replica A might internally represent some history as:
-```text
-[A B C] [D E]
-```
+Compaction can remove the acknowledged masks and remove deleted Frames from retained Footage.
-Replica B might represent the same canonical history as:
+If only part of a positive Insertion was deleted:
 ```text
-[A] [B C] [D] [E]
+A B C D
 ```
-A hydrated replica may create yet another local representation.
-As long as all of them agree on:
+with:
 ```text
-canonical identities
-canonical anchors
-original Frame coordinates
-deterministic Structural Order
+B C
 ```
-they represent the same Sequence.
-Convergence is therefore defined over logical history and Projection, not over internal memory layout.
----
-# Three coordinate spaces
-Many apparent complexities in Sequencer become much simpler when three different coordinate spaces are kept separate.
-## Projection positions
-These are the indexes applications use:
+gone, the retained positive history can shrink to the surviving content:
 ```text
-0, 1, 2, 3, ...
+A D
 ```
-They describe the visible sequence right now.
+Anchors and remaining removals that referred to the old coordinates are adjusted to the smaller retained coordinate space.
-They are temporary.
+The running Projection does not need to be rewritten when this happens. Compaction produces another retained description of the same history.
----
+## Collapsed historical points
-## Canonical logical coordinates
+Compaction can make two old logical points collapse onto the same retained point.
-These identify Frames and boundaries inside original Insertions.
-They survive:
+Imagine:
 ```text
-concurrent edits
-fragmentation
-removal
-reordered delivery
-restart
+A | removed Frames | B
 ```
-These are the coordinates replication cares about.
+with surviving descendants attached on both sides of the removed region.
----
+Before compaction those descendants were separated by different historical coordinates.
-## Runtime structural positions
+After the deleted Frames disappear from retained history, that space no longer exists.
-A live implementation also has some local way to identify materialized pieces of Structural Order.
+Their order has already been resolved in Structural Order, so the compacted history keeps that order when it re-anchors the survivors around the remaining boundary.
-Those positions are purely runtime state.
+The discarded history is no longer needed to make the same ordering decision again.
-Different replicas do not need to share them.
+## Actor retirement
----
+An Actor that will never return would otherwise remain part of acknowledgement consensus forever.
-So:
+Retiring an Actor removes it from future compaction requirements.
-```text
-Projection position
-!=
-canonical logical coordinate
-!=
-runtime structural position
-```
+It does not remove Insertions authored by that Actor.
-Keeping those concepts separate is the easiest way to reason about Sequencer.
+It only changes which Actors must agree before old removal history can be discarded.
----
+Whether an Actor is permanently gone is something the surrounding application has to decide.
-# The model in one example
+## Sequence
-Start with an empty Projection.
+A retained **Sequence** stores enough history to reconstruct the Projection later.
-Replica A inserts:
+It contains canonical Insertion history, acknowledgement frontiers and the Footage belonging to surviving positive history.
-```text
-Hello
-```
+Runtime fragmentation is not persisted as separate Insertions.
-This creates positive canonical history.
-Replica B later receives that history.
-Both now derive:
+If one canonical Insertion currently exists as:
 ```text
-Hello
+[A] [B C] [D]
 ```
-Replica A inserts:
+the retained history still describes the one original Insertion:
 ```text
- world
-```
-at the end.
-If eligible, the existing positive history may simply extend.
-Meanwhile Replica B inserts:
-```text
-beautiful
+A B C D
 ```
-at the same historical boundary.
-Now the replicas contain concurrent history.
+along with the other canonical history that caused its current result.
-They may receive each other's edits in opposite orders.
+The next runtime can fragment it again as needed.
-Because both operations describe stable historical relationships, Sequencer deterministically resolves them.
+## Hydration
-Suppose the resulting Projection is:
+Loading a Sequence rebuilds Structural Order and derives the Projection from it.
-```text
-Hello beautiful world
-```
+A hydrated runtime does not need to reproduce the exact Strip layout of the runtime that saved the Sequence.
-Replica A removes:
+For example, the old runtime may have ended with:
 ```text
-beautiful
+[A] [B C] [D]
 ```
-while Replica B concurrently inserts:
+while the new one initially materializes:
 ```text
-wide
+[A B C D]
 ```
-inside nearby content.
-The removal masks only Frames actually observed by its author.
+If later history needs a boundary inside it, it can split again.
-It cannot accidentally consume the concurrent insertion.
+Both represent the same canonical Insertion.
-Later, all active Actors acknowledge the relevant removal history.
+The visible sequence and the relationships available to future edits remain the same.
-The removed Frames and their masks become eligible for compaction.
+## Projection and history keep changing at different rates
-A persisted snapshot can then omit the obsolete historical region while retaining the already resolved order of everything that survived.
+A Projection can change dramatically while very little canonical history is added.
-A newly hydrated replica reconstructs:
+A long contiguous typing session may extend one positive Insertion.
-```text
-Hello wide world
-```
+A removal can hide many Frames while leaving the positive Insertion itself in history.
-and continues editing from equivalent history.
+Compaction can later make retained history smaller without changing the Projection at all.
-That lifecycle contains almost the entire Sequencer model:
+So these are separate views of the same sequence:
 ```text
-visible positions
-→ canonical anchors
-→ deterministic history
-→ concurrency
-→ fragmentation
-→ masking
-→ acknowledgement
-→ compaction
-→ equivalent reconstruction
+Projection
 ```
----
-# The central idea
-Sequencer works because temporary visible positions are never treated as permanent distributed identities.
-Every edit is translated into stable historical relationships.
-Those relationships can survive:
+is the content visible now.
 ```text
-concurrent editing
-different packet orders
-duplicate delivery
-offline replicas
-fragmentation
-removal
-restart
-compaction
+Structural Order
 ```
-The overall transformation is:
+is the history currently needed to resolve ordering and removals.
 ```text
-local Projection position
-        ↓
-canonical historical relationship
-        ↓
-deterministic Structural Order
-        ↓
-local Projection
+Sequence
 ```
-Every replica may have a different temporary view while history is still arriving.
-Once they know the same canonical history, they can independently derive the same result.
+is the retained form of that history, with acknowledged obsolete history compacted away when possible.
-That is the core of Sequencer.
+An edit starts from the Projection, becomes a relationship in Structural Order, and can eventually survive in a much smaller retained Sequence after the history around it is no longer needed.