Sequencer C++ API¶
sequencer::Projection maintains Structural Order and resolves its visible
Frames. The native runtime owns anchoring, fragmentation, traversal, Session
clocks, pending Insertions, Acknowledgements and snapshot compaction.
The synchronous WebAssembly instance is shared by the TypeScript API. Each Projection retains independent history. JavaScript owns Footage; native spans refer to its binding tokens and array offsets. Application values never enter WebAssembly memory.
Register all active Actors before removals. Equal complete frontiers from every active Actor permit whole-Session compaction: exported Sequences omit eligible masks, deleted Footage and compacted Session claims, while retaining membership. Compaction may translate retained anchors; discarded coordinates are not retained for unregistered offline history.
Implementation¶
class.hppdefines Projection state and operations.algorithms/implements editing, replication, reads and snapshot export.auxiliary/implements anchor resolution, fragmentation and traversal.components/contains the containment, pending and frontier tables.types/type.hppdefines coordinates, Strips, spans and results.bindings.cppexposes numeric inputs and borrowed output views to TypeScript.
The API reference below is generated from the declarations and documentation
in src/c++. Strip indices, original Frame coordinates and visible Projection
positions are distinct; each parameter documents the coordinate space it uses.
See How Sequencer works for the sequence model.
API reference¶
-
class ContainmentTable¶
- #include <class.hpp>
Maps exact canonical identities to roots; runtime fragments are not separate identities.
Public Functions
-
inline Index get(Word session, Word start) const¶
Finds the root for an exact identity.
- Parameters:
session – Authoring Session, not the anchor Session.
start – Logical Insertion start.
- Returns:
Canonical root index, or none when not materialized.
-
inline bool has(const Coordinates &c) const¶
Tests materialization independently of anchor coordinates and Footage.
- Parameters:
c – Coordinates whose authoring identity is queried.
- Returns:
Whether that canonical Insertion has a root.
-
inline void reserve(Word capacity)¶
Reserves identity slots before hydrating a known record count.
- Parameters:
capacity – Required identity capacity, excluding fragments.
-
inline void set(const Coordinates &c, Index strip)¶
Registers or replaces an identity’s canonical root.
- Parameters:
c – Coordinates supplying Session and start.
strip – Nonzero materialized root index.
-
inline Index get(Word session, Word start) const¶
-
struct Slot¶
Open-addressed identity slot; strip zero marks an unused slot.
-
struct ContentAppend¶
- #include <type.hpp>
Deferred content concatenation accompanying an Insertion extension.
Public Members
-
struct Coordinates¶
- #include <type.hpp>
Canonical six-word Insertion coordinates; runtime fragmentation leaves these intact.
Public Functions
-
inline bool birth() const¶
Tests for the virtual root.
- Returns:
Whether the anchor triple is (0, 0, 0).
-
inline bool extension() const¶
Recognizes positive logical continuation without a new zero reservation.
- Returns:
Whether same-Session identity begins at the parent’s anchored endpoint.
Public Members
-
inline bool birth() const¶
-
struct Entry¶
- #include <type.hpp>
Discriminated Gossip entry; only the selected Insertion or frontier is meaningful.
Public Members
-
Acknowledgement frontier¶
Actor Acknowledgement when acknowledgement is true.
Public Static Functions
-
static inline Entry acknowledge(Acknowledgement a)¶
Creates a Acknowledgement entry, retaining its numeric storage.
- Parameters:
a – Actor ID and removal Session/frontier pairs.
- Returns:
Acknowledgement-tagged entry.
-
Acknowledgement frontier¶
-
class FrontierTable¶
- #include <class.hpp>
Actor membership and equal complete Session frontiers governing whole-Session compaction.
Public Functions
-
inline std::unordered_set<Word> compactable() const¶
Finds whole-Session consensus across complete active membership.
- Returns:
Sessions with equal reported frontiers from every active Actor.
-
inline std::vector<Acknowledgement> frontiers() const¶
Exports retained active membership and Acknowledgements.
- Returns:
Acknowledgements in Actor and Session admission order.
-
inline void observe(const Acknowledgement &a)¶
Observes an Actor’s reported removal frontiers, admitting active Actors.
- Parameters:
a – Actor ID followed by Session/end pairs; retired Actors are ignored.
-
inline std::unordered_set<Word> compactable() const¶
-
struct Session¶
-
struct Insertion¶
- #include <type.hpp>
Native Insertion plus an opaque JavaScript Footage reference.
Public Members
-
bool content_owned¶
Whether Footage is privately writable; false requests copy-on-write before masking.
-
Coordinates coordinates¶
Historical anchor, canonical identity and original Frame effect.
-
bool content_owned¶
-
class PendingTable¶
- #include <class.hpp>
Holds canonical operations until their parent’s required logical extent exists.
Public Functions
-
inline void set(Insertion i)¶
Retains an operation without allocating a linked Strip.
- Parameters:
i – Unresolved Insertion; Footage is retained through its numeric binding token.
-
inline std::size_t size() const¶
Counts unresolved canonical parent identities.
- Returns:
Dependency bucket count, not waiting operation count.
-
inline std::vector<Insertion> take(const Coordinates &c)¶
Removes the waiters for a materialized or extended parent.
- Parameters:
c – Parent coordinates whose Session/start key has become available.
- Returns:
Waiters in arrival order; apply preserves that order with a reversed stack push.
-
inline void set(Insertion i)¶
-
class Projection¶
- #include <class.hpp>
Visible Projection of a replicated Sequence.
Public Functions
-
inline Index allocate(Insertion i)¶
Allocates an unlinked Strip; linking, counts and containment are separate.
- Parameters:
i – Canonical coordinates and JavaScript binding reference.
- Returns:
Stable arena index.
-
std::int32_t anchor_strip(Index incoming, Index anchor, Word point, bool index_fragments = true)¶
Places a Strip in deterministic Structural Order and materializes mask continuations.
- Parameters:
incoming – Unlinked Strip to place.
anchor – Current owner of the logical boundary; none for the virtual root.
point – Boundary relative to the owning Insertion or mask.
index_fragments – Whether to maintain jumps while linking secondary mask fragments.
- Returns:
Actual signed visible effect across all materialized fragments.
-
Result apply(std::span<const Entry> gossip)¶
Integrates canonical operations and releases newly satisfied dependencies.
- Parameters:
gossip – Already read native entries; transport validation occurs at the ABI.
- Returns:
Ordered visible Splices and Gossip containing Acknowledgements.
-
void apply(std::span<const Entry> gossip, Result &result)¶
Integrates operations into retained output storage without clearing existing results.
- Parameters:
gossip – Already read native entries.
result – Output to append to, allowing one Result across an entire ABI batch.
-
Word extend(Index origin, Word count, Word content, Word source_start = 0)¶
Appends a contiguous logical suffix while respecting remote fragmentation.
- Parameters:
origin – Existing positive canonical root.
count – Number of newly visible Frames.
content – Binding carrying the incoming suffix.
source_start – Offset of that suffix in its source Footage.
- Returns:
Visible start of the added suffix.
-
std::pair<Word, Index> find_containing_fragment(Index origin, const Coordinates &coordinates, Index incoming = none)¶
Resolves a historical anchor through fragments and already consumed Frames.
- Parameters:
origin – Canonical parent root, or a known fragment from which to continue.
coordinates – Canonical anchor and authored effect; positive queries resolve boundaries.
incoming – Strip whose negative effect may be shortened by overlap; none for boundary queries.
- Returns:
Resolved logical boundary and its current owning Strip.
-
Word find_frame(Word position, bool for_insertion = false)¶
Resolves a visible position and retains the owning Strip as gate.
- Parameters:
position – Visible Frame position, or insertion boundary when requested.
for_insertion – Whether logical boundaries may resolve through hidden history.
- Returns:
Original Frame coordinate within the gate Insertion.
-
void hydrate(const Gossip &insertions, const std::vector<Acknowledgement> &frontiers)¶
Reconstructs trusted exported history and prebuilds traversal jumps.
- Parameters:
insertions – Canonical Insertions in exported Structural Order.
frontiers – Retained Actor Acknowledgements.
-
Insertion insert(Word count, Word content, Word at)¶
Authors positive Frames, extending only an eligible local Insertion.
- Parameters:
count – Positive Footage length.
content – JavaScript binding token; native code never reads the values.
at – Visible insertion boundary.
- Returns:
Canonical Gossip operation, including only the suffix for an extension.
-
void insert_first(Index i)¶
Initializes structural and visible endpoints for the first root.
- Parameters:
i – Unlinked root Strip in an empty Structural Order.
-
inline Word length() const¶
Reads visible length without structural traversal.
- Returns:
Maintained visible Frame count.
-
Result merge(const Gossip &insertions, const std::vector<Acknowledgement> &frontiers)¶
Integrates snapshot history and then observes its retained Acknowledgements.
- Parameters:
insertions – Canonical snapshot Insertions.
frontiers – Snapshot Acknowledgements.
- Returns:
Visible Splices and Gossip containing Acknowledgements for newly integrated history.
-
void own_content(Index fragment)¶
Requests private Footage before clearing externally owned content slots.
- Parameters:
fragment – Any fragment of the positive canonical Insertion.
-
void patch_jumps(std::int32_t frame_diff, Word strip_diff, Index incoming)¶
Updates and, when necessary, splits the jump spanning a local edit.
- Parameters:
frame_diff – Signed change to visible distance.
strip_diff – Added structural Strip count.
incoming – Strip marking the edit boundary.
-
Word position_of(Index strip, std::int32_t gate_diff = 0, bool locate = true)¶
Locates a newly linked Strip relative to the retained local gate.
- Parameters:
strip – Strip whose visible start is required.
gate_diff – Effect already applied before the retained gate boundary.
locate – Whether to resolve an absolute position after repairing local jumps.
- Returns:
Visible Projection position, or zero when only repairing jumps.
-
inline Projection(Word actor_id, Word increasing_session, Word decreasing_session)¶
Initializes empty history with independently supplied Session identities.
- Parameters:
actor_id – Acknowledging Actor.
increasing_session – Session for locally authored positive Insertions.
decreasing_session – Session for locally authored reducing Insertions.
-
Gossip remove(Word start, std::int64_t end)¶
Authors masks for each original Insertion crossed by an inclusive visible range.
- Parameters:
start – First removed Projection position.
end – Last removed position; start greater than end represents an empty range.
- Returns:
Reducing Insertions followed by the local removal Acknowledgement.
-
Gossip replace(Word count, Word content, Word start, std::int64_t end)¶
Authors removal, then insertion against the resulting visible boundary.
- Parameters:
count – Replacement Frame count; zero means removal only.
content – Replacement Footage binding.
start – First replaced Projection position.
end – Last replaced position, inclusive.
- Returns:
Gossip preserving removal-before-insertion order.
-
std::pair<Word, Index> select_anchor(Word position)¶
Translates a visible insertion boundary into a replayable logical anchor.
- Parameters:
position – Insertion boundary in 0..frame_count.
- Returns:
Logical point and its anchoring Strip.
-
Sequence sequence() const¶
Exports equivalent retained state without rewriting live history.
- Returns:
Snapshot with acknowledgement-gated removal compaction.
-
Index split_strip(Index anchor, Word point, std::int32_t incoming_diff)¶
Splits materialization without changing canonical Insertion coordinates.
- Parameters:
anchor – Strip containing the logical boundary.
point – Original Frame boundary, relative to its canonical Insertion.
incoming_diff – Incoming visible effect; negative values consume the right prefix.
- Returns:
Structural successor at the new boundary.
-
Index subtree_end(Index root)¶
Finds a competitor’s final descendant so sibling subtrees stay contiguous.
- Parameters:
root – First Strip of the causal subtree.
- Returns:
Last Strip belonging to that subtree.
-
inline Word traversal_spacing()¶
Reuses square-root spacing until Structural Order crosses its next rounding boundary.
- Returns:
At least one Strip per target jump interval.
Public Members
-
std::vector<ContentAppend> appended¶
Deferred suffix appends joining content under an existing Insertion binding.
-
ContainmentTable containment¶
Canonical Insertion identity to materialized root.
-
std::vector<Span> copied¶
Deferred copy-on-write slices protecting caller arrays and retained snapshots.
-
FrontierTable frontier¶
Actor membership and Acknowledgements used only by export compaction.
-
std::array<Word, 2> increase_clock¶
Independent positive and reducing clocks, each stored as [Session, next time].
-
std::array<Word, 2> jump_spacing¶
Rounded jump spacing and the largest Strip count for which it remains valid.
-
PendingTable pending¶
Unresolved Insertions grouped by their missing canonical parent.
-
inline Index allocate(Insertion i)¶
-
struct Result¶
- #include <type.hpp>
Output of applying operations against a live Projection.
-
struct Sequence¶
- #include <type.hpp>
Retained numeric history and ordered Footage spans for snapshot export.
-
struct SnapshotWords¶
- #include <snapshotWords.hpp>
Streaming snapshot metadata writer; compression preserves every canonical coordinate.
Public Functions
-
inline void append(const Coordinates &c)¶
Appends one retained canonical record, promoting at the 64th record.
- Parameters:
c – Exact exported coordinates after any acknowledgement-gated compaction.
-
inline void promote()¶
Promotes the bounded plain prefix while preserving ACK values and record order.
Public Members
-
bool eligible¶
Whether live root count makes promotion possible; retained count decides it.
-
bool packed¶
Whether the destination has promoted to the compact header and variable records.
-
Coordinates previous¶
Last compact record, used to predict Session and logical start.
-
inline void append(const Coordinates &c)¶
-
struct Span¶
- #include <type.hpp>
JavaScript Footage slice; no application values enter WASM.
-
struct Splice¶
- #include <type.hpp>
Consumer-visible mutation; the removal end is exclusive.
-
struct Strips¶
- #include <type.hpp>
Strip materialization in one arena with separate traversal lanes (SoA).
Canonical coordinates and binding references remain grouped as Insertions; hot fragment/link fields use indexed lanes. Growth preserves indices, not pointers.
Public Functions
-
inline Index append(Insertion insertion)¶
Adds an unlinked Strip initialized with its original signed Frame effect.
- Parameters:
insertion – Canonical Insertion and binding reference.
- Returns:
Stable arena index, unaffected by subsequent growth.
-
inline void reserve(Word next)¶
Grows every lane together, preserving initialized slots and stable indices.
- Parameters:
next – Required arena capacity; existing capacity is retained when sufficient.
-
inline Strips()¶
Initializes slot zero so absent links may safely read zero-valued lanes.
Public Members
-
std::int32_t *fragment_diff¶
Current signed effect; overlaps can leave a mask with zero visible effect.
-
Insertion *identity¶
Canonical coordinates and binding references, repeated across an Insertion’s fragments.
-
inline Index append(Insertion insertion)¶
-
namespace sequencer¶
Typedefs
-
using Gossip = std::vector<Entry>¶
Ordered operations and Acknowledgements transported between replicas.
-
using Index = Word¶
Stable Strip arena index; distinct from a Projection position or logical time.
Functions
-
inline bool anchors_overlap(const Coordinates &a, const Coordinates &b)¶
Tests sibling competition by exact canonical anchor, not intersecting Frame ranges.
-
inline bool competition_is_larger(const Coordinates &a, const Coordinates &b)¶
Tests whether an existing sibling belongs closer to the anchor than incoming a.
- Parameters:
a – Incoming same-anchor competitor.
b – Existing competitor: positives precede masks, then larger Session/start wins.
- Returns:
Whether b precedes a; duplicate identity is handled before ordering.
-
inline bool contains_anchor(const Coordinates &a, const Coordinates &c, Word start, Word end)¶
Tests a child’s canonical parent and inclusive logical boundary interval.
-
inline std::uint64_t identity(Word session, Word start)¶
Packs a canonical identity without hashing or truncating either coordinate.
- Parameters:
session – Authoring Session.
start – Logical start within that Session.
- Returns:
Exact identity key; the anchor is deliberately excluded.
-
void link_jumps(Projection &p, Index left, Index right, Word frames, Word strips)¶
Replaces a bidirectional jump and detaches conflicting reverse links.
- Parameters:
p – Projection whose traversal index changes.
left – Left endpoint in Structural Order.
right – Right endpoint in Structural Order.
frames – Visible Frames crossed, counting the left endpoint but not the right.
strips – Structural steps between endpoints, including hidden Strips.
-
using Gossip = std::vector<Entry>¶
-
namespace [anonymous]¶
-
namespace std¶
STL namespace.
- file apply.cpp
- #include “../auxiliary/linkJumps.hpp”#include “../class.hpp”#include <algorithm>
Integrates canonical history while preserving local traversal and consumer Splice order.
- file create.cpp
- #include “../auxiliary/linkJumps.hpp”#include “../class.hpp”#include <algorithm>#include <unordered_map>
Hydrates canonical history and builds its initial visible traversal index.
- file insert.cpp
- #include “../auxiliary/containsAnchor.hpp”#include “../class.hpp”
Authors stable positive Insertions from local visible boundaries.
- file merge.cpp
- #include “../class.hpp”
Merges retained operations without replacing a live Projection’s independent history.
- file remove.cpp
- #include “../class.hpp”#include <algorithm>
Translates visible removal ranges into masks over original Insertion Frames.
- file replace.cpp
- #include “../class.hpp”
Preserves removal-before-insertion semantics in one locally authored Gossip batch.
- file sequence.cpp
- #include “../auxiliary/magnitude.hpp”#include “../auxiliary/snapshotWords.hpp”#include “../class.hpp”#include <algorithm>#include <limits>#include <unordered_map>
Exports compactable history while preserving hydrated Projection and future ordering.
- file values.cpp
- #include “../class.hpp”#include <algorithm>
Resolves visible ranges to ordered binding spans without reading application values.
- file anchorsOverlap.hpp
- #include “../types/type.hpp”
- file anchorStrip.cpp
- #include “../class.hpp”#include “anchorsOverlap.hpp”#include “competitionIsLarger.hpp”#include “magnitude.hpp”#include <algorithm>
Resolves sibling competition, original-Frame masking and causal subtree placement.
- file competitionIsLarger.hpp
- #include “../types/type.hpp”
- file containsAnchor.hpp
- #include “../types/type.hpp”
- file extendInsertion.cpp
- #include “../class.hpp”#include “containsAnchor.hpp”#include <algorithm>
Materializes a positive Insertion suffix under its existing canonical identity.
- file findContainingFragment.cpp
- #include “../class.hpp”#include “magnitude.hpp”#include <algorithm>
Finds the current owner of a historical logical boundary through fragments and masks.
- file findFramePositionByProjectionPosition.cpp
- #include “../class.hpp”#include “linkJumps.hpp”#include “magnitude.hpp”#include <algorithm>
Translates visible positions to original Frame coordinates and maintains local jumps.
- file findProjectionPositionOfStrip.cpp
- #include “../class.hpp”#include “linkJumps.hpp”#include <algorithm>#include <optional>
Finds a linked Strip’s visible boundary without resetting the retained local gate.
- file insertFirst.cpp
- #include “../class.hpp”
Initializes the first structural root; later roots must use sibling competition.
- file linkJumps.cpp
- #include “linkJumps.hpp”
Maintains symmetric jump endpoints and their visible and structural distances.
- file linkJumps.hpp
- #include “../class.hpp”
- file magnitude.hpp
- #include “../types/type.hpp”
- file ownContent.cpp
- #include “../class.hpp”
Defers JavaScript copy-on-write and rebases every fragment sharing a binding.
- file patchJumps.cpp
- #include “linkJumps.hpp”#include <algorithm>
Repairs jump distances after a local insertion or mask changes Structural Order.
- file selectAnchor.cpp
- #include “../class.hpp”#include “containsAnchor.hpp”#include “magnitude.hpp”
Selects stable logical anchors for local visible insertion boundaries.
- file snapshotWords.hpp
- #include “../types/type.hpp”
- file splitStrip.cpp
- #include “../class.hpp”#include “magnitude.hpp”#include <algorithm>
Splits runtime materialization while preserving original coordinates and Footage identity.
- file subtreeEnd.cpp
- #include “../class.hpp”#include “containsAnchor.hpp”#include “linkJumps.hpp”#include “magnitude.hpp”#include <algorithm>
Keeps each exact-anchor competitor together with its entire causal subtree.
- file bindings.cpp
- #include “class.hpp”#include <algorithm>#include <bit>#include <limits>#include <memory>#include <span>#include <unordered_set>
Synchronous wasm32 ABI: numeric input, borrowed output views and opaque Footage tokens.
Defines
-
EMSCRIPTEN_KEEPALIVE¶
Functions
-
void runtime_create(std::uint32_t id, std::uint32_t actor)¶
Allocates independent native history in the shared module.
- Parameters:
id – JavaScript-assigned Projection handle.
actor – Actor used for Acknowledgements.
-
void runtime_destroy(std::uint32_t id)¶
Releases the native history at a handle, including its pending dependencies.
- Parameters:
id – Handle to release; absent handles are harmless.
-
std::uint32_t *runtime_dispatch(std::uint32_t operation, std::uint32_t id, std::uint32_t arg0, std::uint32_t arg1, std::uint32_t arg2, const std::uint32_t *pointer, std::uint32_t count)¶
Executes a general operation and exposes output until the next native call.
- Parameters:
operation – Dispatch opcode shared with the TypeScript protocol.
id – Live Projection handle, or the handle to create or destroy.
arg0 – First operation-specific scalar.
arg1 – Second scalar, including the first content token for snapshot input.
arg2 – Third scalar, including snapshot shape validity for create and merge.
pointer – Numeric input buffer; application content never enters this memory.
count – Input word count.
- Returns:
Twelve-word output header with byte pointers and element counts.
-
const std::uint32_t *runtime_insert(std::uint32_t id, std::uint32_t count, std::uint32_t content, std::uint32_t at)¶
Authors local positive Frames without general result descriptors.
- Parameters:
id – Live Projection handle.
count – Positive Frame count supplied by trusted local code.
content – JavaScript token for the incoming Footage.
at – Visible insertion boundary.
- Returns:
Six coordinate words and an optional append target, endpoint and content origin.
-
std::uint32_t runtime_length(std::uint32_t id)¶
Reads maintained visible length through the dedicated scalar path.
- Parameters:
id – Live handle; the JavaScript wrapper excludes destroyed instances.
- Returns:
Visible Frame count.
-
std::uint32_t *runtime_reserve(std::uint32_t count)¶
Reserves writable numeric input; memory growth may invalidate the previous heap view.
- Parameters:
count – Required word count, not bytes.
- Returns:
Borrowed input buffer for the next dispatch.
-
EMSCRIPTEN_KEEPALIVE¶
- file class.hpp
- #include “components/ContainmentTable/class.hpp”#include “components/FrontierTable/class.hpp”#include “components/PendingTable/class.hpp”#include <cmath>#include <span>#include <stdexcept>
- file class.hpp
- #include “../../types/type.hpp”
- file class.hpp
- #include “../../types/type.hpp”#include <algorithm>#include <unordered_map>#include <unordered_set>
- file class.hpp
- #include “../../types/type.hpp”#include <algorithm>#include <unordered_map>#include <unordered_set>
- file type.hpp
- #include <algorithm>#include <array>#include <bit>#include <cstddef>#include <cstdint>#include <cstring>#include <memory>#include <optional>#include <vector>
- dir algorithms
- dir auxiliary
- dir components
- dir components/ContainmentTable
- dir components/FrontierTable
- dir components/PendingTable
- dir types