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

@sovereignbase/sequencer 1.0.0 → 1.0.2

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.
+inside that original Insertion.
----
+If later edits move `C` somewhere else in the Projection, this point is still point `2` of the same original Insertion.
-## Frames and logical points are different
+## Anchoring an edit
-Consider an Insertion containing:
+Suppose the Projection contains:
 ```text
-A B C
-```
-It contains three Frames:
-```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.
-Visible positions move.
-Historical logical points do not.
+The same anchor still refers to the point after `Hello ` in the original Insertion.
----
+The Projection position is different, but the relationship is the same.
-# From a local edit to canonical history
+## Insertion identity
-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.
-The numeric Projection position may differ.
-The historical relationship does not.
+A new independent Insertion normally starts after another reserved logical point:
----
-# Structural Order
+```text
+0 1 2 | 3
+          ↑
+       boundary
-Canonical history must eventually form one deterministic order.
+next start = 4
+```
-Sequencer calls this **Structural Order**.
+The gap gives the previous Insertion its own endpoint without making that endpoint the identity of the next independent Insertion.
-Structural Order contains everything required to explain the visible sequence, including history that may no longer itself be visible.
+Positive and reducing history use separate Sessions.
-It may contain:
+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.
-```text
-positive Insertions
-removal history
-fragments
-concurrent siblings
-causal descendants
-hidden historical boundaries
-```
+## Structural Order
-The Projection is derived from this structure.
+Every materialized Insertion is placed into one Structural Order.
-Conceptually:
+Suppose the original history is:
 ```text
-Structural Order
-        ↓
-surviving positive Frames
-        ↓
-Projection
+A B
 ```
-Structural Order is therefore richer than the visible sequence.
-The Projection answers:
+and a new Insertion anchors between them:
 ```text
-what is visible now?
+A | B
 ```
-Structural Order answers:
+Structural Order can now represent:
 ```text
-what historical relationships produced that result?
+A X B
 ```
----
-# 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:
-```text
-X
-Y
-```
-The order between them cannot depend on which replica received which packet first.
-Sequencer therefore defines a deterministic competitor ordering.
-Closer to the shared anchor:
+They must get the same order on every replica even when they arrive in different orders.
-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.
+Sequencer orders competing Insertions from the anchor outward by:
-Every replica can calculate this from the canonical history alone.
+1. positive Insertions before reducing Insertions;
+2. greater Session first;
+3. within the same Session, greater start first.
-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
-# Causal subtrees stay together
+An Insertion can have more history attached to it.
-A concurrent competitor may later receive children of its own.
+Suppose two replicas start from an empty sequence.
-Those children form its **causal subtree**.
-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.
-The two roots compete at the same virtual root anchor.
-Sequencer deterministically decides which root comes first.
+and continues editing that.
-But the descendants of each root must remain with that root.
+The two initial Insertions compete at the 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**.
-The important point is that they are not new canonical Insertions.
-Both still belong to the same original history:
-```text
-same anchor
-same insertion identity
-same original coordinate space
-```
+These pieces are **Strips**.
-They merely represent different portions of it at runtime.
+Both Strips still belong to the same original Insertion.
-Conceptually:
+The original coordinate space is still:
 ```text
-canonical Insertion
 | A | B | C | D |
 0   1   2   3   4
-         ↓
-runtime materialization
-[A B]       [C D]
 ```
-The logical points remain:
+The left Strip represents one part of that space and the right Strip represents another.
-```text
-0 1 2 3 4
-```
+An operation authored earlier against point `3` can still find point `3` even though the original Insertion is no longer represented by one Strip.
-even if the current physical representation is split around point `2`.
+Different replicas can also have different fragmentation.
-This allows old operations to continue referring to historical locations after arbitrary later 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:
-```text
-which Insertion it is
-```
-and:
-```text
-which original logical point an anchor refers to
-```
-They do not need identical runtime layouts.
-The receiver resolves canonical coordinates through whatever fragmentation exists locally.
+They still agree on the original Insertion and its coordinates.
-Runtime fragmentation is therefore invisible to replication.
+## Extending an Insertion
----
+Consecutive editing often continues the Insertion that was just created.
-# 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.
-Sequencer can instead extend a recent positive Insertion when the new edit is a genuine continuation of that same history.
+does not need five unrelated canonical Insertions.
-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
-Removing visible content does not immediately erase its original Insertion.
-Instead, removal is represented as new history.
-A removal is a reducing Insertion:
-```text
-insertionDiff < 0
-```
+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.
-which targets original Frames belonging to a positive Insertion.
+## Removal
-This is best understood as **masking**.
+Removal is represented by reducing Insertions.
-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.
-# Why removal must target original Frames
+This becomes especially useful when insertion and removal happen concurrently.
-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.
-Because removal targets original Frames rather than a mutable visible interval, it masks only:
+The removal authored by A refers to the original Frames of `old `.
-```text
-old
-```
+It never referred to `small ` because those Frames did not exist in A's history.
-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,233 @@ while another removes:
 fox jumps
 ```
-Both removals refer to original Frames.
+Both target the original Frames of `fox`.
-The Frames belonging to:
-```text
-fox
-```
+When the second removal is integrated, those Frames may already be masked.
-were targeted twice.
-They must still disappear only once from the Projection.
-A reducing Insertion therefore retains its canonical authored meaning while its current runtime effect is resolved against Frames that remain available to consume.
-This guarantees:
-```text
-one original Frame cannot reduce the Projection twice
-```
+They cannot reduce the Projection again.
-Delivery order cannot cause repeated subtraction or make deleted content reappear.
+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.
----
+This lets overlapping removals arrive in either order without changing the result.
-# Replacement is composition
+## Replacement
-Replacement does not require its own structural concept.
+Replacement is a removal followed by a positive Insertion.
-Replacing:
+Changing:
 ```text
 Draft
 ```
-with:
+to:
 ```text
 Final
 ```
-is simply:
+first masks the Frames of:
 ```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:
-```text
-resolved order
-```
-can become more important than:
-```text
-the exact historical path that originally produced it
+Draft
 ```
-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:
+and then anchors:
 ```text
-live Structural Order
-        ↓
-derive equivalent compacted history
-        ↓
-persist / transfer snapshot
+Final
 ```
-A later Projection can hydrate from that compacted history and produce the same visible state and compatible future ordering.
+into the resulting history.
-This keeps persistence optimization separate from the current editing runtime.
+Both parts use the same insertion and removal rules as every other edit.
----
+## Actors and acknowledgements
-# Actor retirement
+Removal history cannot always be discarded when it disappears from the Projection.
-A permanently gone Actor would otherwise block removal compaction forever.
+Suppose one replica removes some Frames while another replica is offline.
-Sequencer therefore allows an Actor to be retired from future acknowledgement consensus.
+The offline replica may still have unsent history anchored to those Frames.
-Retirement means:
+The removed Frames must remain addressable until that old history no longer needs to be supported.
-```text
-this Actor is no longer expected to acknowledge future compaction
-```
+Actors report how far they have observed each reducing Session.
-It does not mean:
+For example:
 ```text
-delete history authored by this Actor
-```
-Those are unrelated concepts.
-Retirement is an application-level decision because Sequencer cannot know whether a disconnected replica is temporarily offline or permanently abandoned.
----
-# Persistence retains history, not runtime state
-A persisted Sequence contains the history needed to reconstruct the Projection.
+Actor 3
-It does not need to persist every runtime optimization.
-For example, persistence needs the equivalent of:
-```text
-canonical Insertions
-retained acknowledgement state
-positive Footage
+removal Session 17
+observed through logical time 42
 ```
-It does not need to preserve things such as:
-```text
-current fragmentation layout
-temporary traversal indexes
-recent lookup positions
-allocation addresses
-```
+The reported point is a **frontier**.
-Those can be reconstructed.
+A single frontier summarizes a received prefix of a Session rather than acknowledging every reducing Insertion separately.
-The persistence boundary therefore follows the same conceptual separation as replication:
+Every active Actor, including an offline Actor, must be registered before removals. An Actor-only acknowledgement such as `[3]` establishes that membership. Constructing another Projection does not register its Actor in the other replicas.
-```text
-stable history is durable
-runtime materialization is disposable
-```
+The application must exchange pending history before treating an acknowledgement as a complete Session frontier. The library reports receipt of reducing Insertions; it does not prove that missing earlier operations have arrived.
----
+## Compaction
-# Hydration reconstructs an equivalent Projection
+When all active Actors agree on the same frontier for a reducing Session, the acknowledged part can be removed from future retained Sequences.
-When retained history is loaded again, Sequencer reconstructs the structural relationships encoded by that history and derives the visible Projection.
+This is whole-Session eligibility: every active Actor must report the same complete Session frontier. A missing claim or a different endpoint blocks that Session. Taking the minimum of unequal frontiers is not this compaction rule.
-The important requirement is not that the new runtime representation be byte-for-byte identical to the previous one.
+Eligible masks must disappear from the exported Sequence. Wholly removed positive Insertions and deleted Footage disappear as well. Claims for compacted Sessions are dropped; Actor membership is retained.
-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.
----
+and every active Actor has seen the removal.
-# The same history can have different runtime shapes
+A new retained Sequence no longer needs to preserve all of the machinery that represented that deletion.
-This is a useful general principle.
+Compaction can remove the acknowledged masks and remove deleted Frames from retained Footage.
-Replica A might internally represent some history as:
+If only part of a positive Insertion was deleted:
 ```text
-[A B C] [D E]
+A B C D
 ```
-Replica B might represent the same canonical history as:
+with:
 ```text
-[A] [B C] [D] [E]
+B C
 ```
-A hydrated replica may create yet another local representation.
-As long as all of them agree on:
+gone, the retained positive history can shrink to the surviving content:
 ```text
-canonical identities
-canonical anchors
-original Frame coordinates
-deterministic Structural Order
+A D
 ```
-they represent the same Sequence.
+Anchors and remaining removals that referred to the old coordinates are adjusted to the smaller retained coordinate space.
-Convergence is therefore defined over logical history and Projection, not over internal memory layout.
+The running Projection does not need to be rewritten when this happens. Compaction produces another retained description of the same history.
----
+The exported Sequence is a retained checkpoint. Its shorter Insertions and translated anchors can use different coordinates from the live graph before export. Continued editors must use compatible retained state; a compacted checkpoint does not preserve a permanent mapping to discarded history.
-# Three coordinate spaces
+An offline Actor's unacknowledged history blocks compaction only if that Actor was registered. A test that omits its membership, allows compaction, then demands that its discarded anchors still work is outside this contract. Tests must not retain masks to satisfy that demand.
-Many apparent complexities in Sequencer become much simpler when three different coordinate spaces are kept separate.
+## Collapsed historical points
-## Projection positions
+Compaction can make two old logical points collapse onto the same retained point.
-These are the indexes applications use:
+Imagine:
 ```text
-0, 1, 2, 3, ...
+A | removed Frames | B
 ```
-They describe the visible sequence right now.
-They are temporary.
----
+with surviving descendants attached on both sides of the removed region.
-## Canonical logical coordinates
+Before compaction those descendants were separated by different historical coordinates.
-These identify Frames and boundaries inside original Insertions.
+After the deleted Frames disappear from retained history, that space no longer exists.
-They survive:
-```text
-concurrent edits
-fragmentation
-removal
-reordered delivery
-restart
-```
+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.
-These are the coordinates replication cares about.
+The discarded history is no longer needed to make the same ordering decision again.
----
+## Actor retirement
-## Runtime structural positions
+An Actor that will never return would otherwise remain part of acknowledgement consensus forever.
-A live implementation also has some local way to identify materialized pieces of Structural Order.
+Retiring an Actor removes it from future compaction requirements.
-Those positions are purely runtime state.
+It does not remove Insertions authored by that Actor.
-Different replicas do not need to share them.
+It only changes which Actors must agree before old removal history can be discarded.
----
-So:
-```text
-Projection position
-!=
-canonical logical coordinate
-!=
-runtime structural position
-```
-Keeping those concepts separate is the easiest way to reason about Sequencer.
----
-# The model in one example
-Start with an empty Projection.
-Replica A inserts:
-```text
-Hello
-```
+Whether an Actor is permanently gone is something the surrounding application has to decide.
-This creates positive canonical history.
+## Sequence
-Replica B later receives that history.
+A retained **Sequence** stores enough history to reconstruct the Projection later.
-Both now derive:
+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.
-Replica A inserts:
+If one canonical Insertion currently exists as:
 ```text
- world
+[A] [B C] [D]
 ```
-at the end.
-If eligible, the existing positive history may simply extend.
-Meanwhile Replica B inserts:
+the retained history still describes the one original Insertion:
 ```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.