@fluidframework/tree 2.0.0-dev-rc.1.0.0.224419

package/docs/main/indexes-and-branches.md

@@ -0,0 +1,143 @@
+# Indexes and Branches
+
+## Indexes
+
+[shared-tree-core](../../src/shared-tree-core/README.md) defines the type `Index` which fills the same role Indexes do [in databases](https://en.wikipedia.org/wiki/Database_index).
+Because of this, shared-tree can be though of as a tree database which is interacted with through a collection of indexes.
+To avoid needing an abstraction to storing the actual underlying document content, all persisted document data is actually owned by the indexes.
+In database terms this means that we use [covering indexes](https://en.wikipedia.org/wiki/Database_index#Covering_index) to answer all queries.
+Concretely this is done by [shared-tree](../../src/shared-tree/README.md) providing a `ForestIndex` which is is a covering index (stores the actual data from each tree node), optimized for retrieving (and editing) parts of subtrees by path.
+Schema data is similarly handled by `SchemaIndex`.
+In the future we will have more index implementations, which can provide functionality like accelerating lookup of nodes (in `ForestIndex`) by identifiers, text search etc.
+
+Indexes are updated when the Fluid document (contents of the Shared Tree) is edited, and are persisted in Fluid summaries.
+
+It is possible to have indexes which only have performance implications (never cause ops to apply differently), which optimistically cache some data in memory and persist nothing.
+For simplicity we will consider these just like persisted indexes, where their persisted information is empty, and this document will focus on solving the harder general problem of indexes which may persist some data.
+
+It is also possible for indexes to only keep a subset of their data in memory, relying on persisted data to load in the rest as needed.
+This is planned for "ForestIndex", and is an important requirement that the design for indexes must support to allow documents to scale beyond memory.
+
+## Branches
+
+A branch is a timeline of a document's state as viewed from a particular user.
+This is the same concept as [branches in version control](<https://en.wikipedia.org/wiki/Branching_(version_control)>).
+From the perspective of a single Fluid client, there can be several relevant branches:
+
+-   The sequenced branch: this includes everything that has been sequenced.
+    It is append-only (never rebased or reset) and consists of all the ops from all the clients, rebased into the canonical order selected by the Fluid ordering service.
+
+    When compared to common `git` workflows, this closely resembles a `main` branch which is only updated via pull requests into an upstream repository.
+
+-   The local branch: the sequenced branch, plus any local edits (ops for them have not yet been sequenced).
+
+    In our `git` metaphor this is a feature branch in the local repository.
+    Every time `main` changes, the feature branch is rebased onto the new state of `main` by making pull requests one
+    commit at a time which are always merged using rebase.
+
+-   The working copy: the local branch, plus the current state of an in progress transaction.
+    If async transactions are supported with snapshot isolation, the version of the local branch that the transaction branches off from might not always be the latest.
+
+    In our `git` metaphor, this lines up with git's working copy, while the "local branch" is checked out.
+    The in progress transaction aligns with the uncommitted changes.
+
+-   Remote branches: branches which replicate what remote clients had in their local branches when an op was sent.
+    These are necessary for correctly rebasing remote edits into main.
+
+    In our `git` metaphor this represents a local copy of a different remote's feature branch.
+    Since in Fluid all the clients do the rebase, but in `git` it happens once in the upstream repository,
+    such branches would generally not be needed if using `git`, but are necessary for our actual Fluid setup.
+
+-   Long lived branches: branches explicitly created by the user that can live separately from the "main" branch for long periods of time.
+
+    In our `git` metaphor this represents feature branches (eventually might be merged) or release branches (likely never merged).
+    They can be used to experiment with a copy of the document, work offline for extended periods while preserving history when merging,
+    or just as a way to have a user-controlled snapshot.
+
+    Currently shared-tree does not use or support this type of branches, but forward looking designs should consider them.
+
+TODO: diagrams showing branch diagram for a couple clients over time.
+
+## Branch Index Interactions
+
+There are several different use-cases for indexes which would necessitate access to them at different times and on different branches.
+
+-   Tip of the "working copy" branch.
+
+    For example, editing code will likely need indexes for the working copy in order to provide access to schema and tree information while editing.
+    If there are additional indexes (ex: subtree lookup from identifier, or text search), these likely would also be desired at the top of the working copy branch.
+
+-   Tip of the "local" branch.
+
+    This is the version typically reflected in the application's views (for example its user interface or exposed via APIs).
+    It needs to support reading and interpreting the state of the document, as well as creating transactions at that state.
+
+-   Tip of the sequenced branch.
+
+    This is a logical branch to record the indexes for summarization, though the tip of the "local" branch could also be used since on summary clients they are the same.
+    Future optimizations to not duplicate state in the summary client might lead to wanting to explicitly summarize the tip of the sequenced branch instead.
+
+    This is also the state onto which edits are rebased (both remote edits, and the local branch).
+    Doing this could make use of indexes at this point.
+
+-   Tip of remote branches.
+
+    This is the state in which remote edits are interpreted and rebased from.
+    Since the creators of the ops had access to indexes at this state (via their local branch),
+    they could optionally include relevant information from those indexes to avoid it having to be recovered when processed/rebased on other client.
+
+-   Along merge reconciliation paths.
+
+    If change rebasing or squashing requires access to indexes, they could be required anywhere along the merge reconciliation paths.
+
+-   Other historical states.
+
+    Inspecting old document versions could make use of old versions of indexes.
+    Another approach to this would be to index history directly, so the current versions of indexes contain the needed historical information.
+
+-   On long lived branches.
+
+    Just like the main branch, if long lived branches are supported, they may needed indexes.
+    They may even need indexes for their corresponding working copies and remote branches if they are used collaboratively.
+
+## Optimizations Options
+
+Maintaining full in-memory versions of all indexes for all these locations all the time would be very expensive performance wise.
+
+This can be mitigated in several different ways:
+
+-   Maintain indexes only at places in the revision graph that require them.
+
+-   Use indexes when creating edits (tip of the "working copy" branch) but not when peer rebasing them.
+    For indexes using this approach this prevents remote edits from requiring indexes to be rebased.
+    This means that synchronously rebasing remote edits does not require index access, so index access can be async.
+    This also (when combined with the above) avoids maintaining most of the possible versions of an index.
+
+-   "Virtualized" indexes which lazily load data from blobs as needed, keeping only a portion of the data in memory at a given time.
+    This can make some accesses async, and thus works well with the above.
+
+-   Delta indexes: implements indexes as deltas to another version of the index which can be used similarly to a write back cache or the tiering in level db.
+    This is a nice design pattern to handle the persisted vs in memory combination, but also generalizes.
+    This can be used to keep multiple in memory versions for nearby locations in the revision graph (ex: persisted, sequenced, local and per transaction).
+
+-   Copy on Write: Copy on write can also be used to optimize maintaining multiple indexes by sharing the parts that are the same.
+
+Note that this list is not complete, but it is sufficient to motivate the decisions below.
+
+## A General Approach
+
+Depending on the specific index, it might be needed at different places, and thus have very different usage patterns and optimization requirements.
+
+To keep as many options open as possible, shared tree's index abstraction can expose both the notion of branches and revisions to the index abstraction.
+This complicates the index abstraction a bit, but leaves the index implementation to pick if mutation or copy on write is a good approach, and if it should do virtualization.
+We then introduce the concept of an "IndexView", which accesses the index's information about a specific revision or branch.
+
+To make implementations of indexes simpler, helper code could be authored for both copy on write and mutation based index approaches (likely involving deltas as well) so this logic does not need to be implemented multiple times.
+
+To avoid having multiple data-structures tracking how different branches relate to each-other, we can generalize `Rebaser` into a `RevisionManager` that can handle this once, and indexes can use it to track/notify/lookup anything needed related to that.
+
+Since indexes can depend on other indexes (like how ForestIndex depends on the SchemaIndex), the RevisionManager can be an index.
+This would remove the need to special case how it stores its state in summaries: it could do so just like all the other indexes.
+
+This approach leaves most of the design tradeoffs inside the index implementations, meaning that changing them will not impact the system architecture.
+This also means that different indexes (or even the same indexes in different apps) can take different approaches, allowing for more specialized optimizations and incremental API migrations when needed.

package/docs/main/modular-change-family.md

@@ -0,0 +1,125 @@
+# Modular Change Family
+
+Merge semantics in `SharedTree` are mostly associated with fields.
+For example, a sequence field has different merge semantics than an optional field does.
+
+`ModularChangeFamily` is an implementation of `ChangeFamily` which delegates work in a given field to the appropriate `FieldKind`.
+A `ModularChangeFamily` instance is parameterized with a set of `FieldKind` implementations.
+
+The purpose of `ModularChangeFamily` is twofold:
+
+1. Encapsulates the logic for handling changes to nodes.
+2. Allow collaborative editing of documents with fields of different kinds.
+
+## Revision Info
+
+Some `FieldKind` implementations need to know which revision a given change is associated with.
+`ModularChangeFamily` keeps track of revision information using `RevisionTag`s so it can provide `FieldKind` implementations with this information when invoking their `rebase`, `invert`, and `compose` functions.
+
+### Revision Info At Rest
+
+First, it's helpful to consider how revision info is maintained in changeset structures.
+Here "at rest" is in opposition to "during rebase/invert/compose".
+
+`ModularChangeFamily` maintains revision info such that for each portion of the changeset that is associated with a specific `RevisionTag`,
+`ModularChangeFamily` is able to recover the `RevisionTag` for that portion.
+The only exception is the case where changes for a single field are contributed by multiple revisions:
+the `ModularChangeFamily` keeps track of the revision info associated with the changes made to the individual subtrees rooted in that field,
+but it doesn't keep track of the revisions associated with the changes in the field itself.
+The responsibility for keeping track of this information falls on the `FieldKind` implementation for that field,
+which may have no need for such information and may therefore not bother maintaining it.
+
+There are four possible locations where revision information can be stored:
+
+1. With the root of the changeset (on `TaggedChange<FieldChangeMap>.revision`)
+2. With the change information associated with a specific field of a specific node (on `FieldChange.revision`)
+3. With the change information associated with the value of a specific node (on `NodeChangeset.valueChange.revision`)
+4. Within the `FieldKind`-specific data on each field (within `FieldChange.change`)
+
+#4 is considered an implementation detail of `FieldKind`s, and is completely opaque to `ModularChangeFamily`.
+The `ModularChangeFamily` implementation is agnostic to the possibility that a `FieldKind` may store such information and therefore does not rely on it.
+In other words, any revision info stored in `FieldKind`-specific data structures does not contribute to `ModularChangeFamily`'s bookkeeping of revision information.
+We ignore #4 in the rest of this document.
+
+In all other cases (#1, #2, and #3) the `revision` field may be either populated or undefined, with the following semantics:
+
+A populated `revision` field indicates that all the changes included on the data structure that sports this `revision` field
+(including recursive changes)
+are associated with the given revision.
+
+An undefined `revision` field can occur in three cases:
+
+    A) When a revision is specified on an ancestor of the current structure, in which case the changes to the current structure (and all nested structures) are associated with that revision.
+    B) When the changes in the current structure (or its nested structures) are associated with multiple revisions.
+    C) When the changes are associated with an anonymous (i.e., tag-less) edit.
+
+C) Is a special case that will likely be excluded in future implementations.
+For now it is treated as a special case of A).
+
+Note that #1 is special in that A) never applies to it (since it is the root).
+Similarly #4 is special in that B) never applies to it (since it only ever represents the change in value prescribed by a single revision).
+
+The above rules mean that, unless a change was contributed by an anonymous edit, at least one populated `revision` field should be encountered when walking down from the root to any given portion of a changeset.
+The above rules do not prescribe that exactly one populated `revision` field will be encountered,
+so any logic based on the above must give precedence to lower (i.e., higher tree depth) revision information.
+
+### Revision Info During Operations
+
+We now consider how revision info flows through the recursive invocations of `rebase`, `invert`, and `compose`.
+
+#### Invert and Rebase
+
+In the `invert` case, `ModularChangeFamily` provides revision information to the `FieldKind`'s `invert` implementation.
+This is accomplished by considering the following sources of revision information:
+
+    i. The field whose changes are being inverted bears revision information (see #2 in the previous section).
+    ii. The field whose changes are being inverted has an ancestor field that bears revision information (#2 again).
+    iii. The field whose changes are being inverted is part of a tagged changeset (see #1)
+
+If none of the three possibilities above yield revision information then an `undefined` revision is passed to the `FieldKind`'s `invert` implementation.
+This can occur in two cases:
+
+-   The changes for the field were contributed by an anonymous change.
+-   The changes for the field were contributed by multiple changes.
+    In this latter case, the `FieldKind`-specific change data
+    (which is opaque to `ModularChangeFamily`)
+    may contain more precise information about which part of the changes are associated with various revisions,
+    but that is entirely left up to the `FieldKind` implementation.
+
+When the `FieldKind`'s `invert` implementation recurses by calling the `NodeChangeInverter`,
+`ModularChangeFamily` is able to determine the revision info of the `NodeChangeset` (and nested changes) by taking into account (in order of highest to lowest precedence):
+
+-   The revision information associated with the field/value changes for that node (see #2 & #3) if present.
+-   The revision information for the field changes within which the `NodeChangeset` is contained (see #i, #ii, #iii).
+
+If neither of these yield a defined revision then the changes to the `NodeChangeset` were either contributed by an anonymous or by multiple changes.
+
+In the `rebase` case, we do not anticipate the `FieldKind`'s `rebase` implementation needing to know the revision info for the change being rebased, so `ModularChangeFamily` does not plumb that information through.
+We do however know that some `FieldKind`'s `rebase` implementation needs to know the revision info for the base change (i.e., the change that is being rebased over) so `ModularChangeFamily` does plumb that information through.
+This is accomplished in the same way as it is for the `invert` implementation.
+
+#### Compose
+
+In the `compose` case, `ModularChangeFamily` does plumb revision info through for all changes.
+This creates a complication when the `FieldKind`'s `compose` implementation calls `NodeChangeComposer`, and `ModularChangeFamily` needs to look up the revision info for the field changes that contain a given `NodeChangeset` passed to `NodeChangeComposer`.
+The complication stems from the fact that `ModularChangeFamily` has no way of determining how the `NodeChangeset`s passed to `NodeChangeComposer` correspond to the field changesets it had passed to the `FieldKind`'s `rebase` implementation.
+For example, if `ModularChangeFamily` calls the `FieldKind`'s `compose` implementation and passes it changesets associated with revisions foo, bar, and baz,
+and the `FieldKind`'s `compose` implementation then invokes the `NodeChangeComposer` with `NodeChangeset`s from the two of the changesets it was given,
+then there's no way for the `ModularChangeFamily` to know whether these two `NodeChangeset`s came from foo and bar, foo and baz, or bar and baz respectively.
+
+There are different ways this complication can be overcome.
+The current implementation requires the caller of the `NodeChangeComposer` to explicitly tag the `NodeChangeset`s it passes.
+
+Note that the ability of `NodeChangeComposer` to recover revision info for each of the `NodeChangeset`s it is given is not only necessary for the sake of passing the adequate revision info to nested field's `compose` implementations,
+it is also necessary for the sake of maintaining the information described in the previous section.
+
+For example, if a pair of `NodeChangeset`s from revisions foo and bar are passed to `NodeChangeComposer`,
+it possible that the given `NodeChangeset`s do not explicitly contain revision data because they relied on a higher field (or the root changeset structure) to indicate their associated revision.
+After these `NodeChangeset`s are composed, the higher fields (and root) will not contain such revision information because those higher fields and root will be composites of multiple changes.
+This means `NodeChangeComposer` must ensure that the `NodeChangeset` it returns is self-sufficient when it comes to describing which of its parts are associated with a given revision.
+
+If the `NodeChangeset` associated with revision foo only carries change information for field "foo" and the `NodeChangeset` associated with revision bar carries change information for the value of the node,
+then the resulting `NodeChangeset` must have:
+
+-   A `FieldChange` for field "foo" carrying the revision foo
+-   A `NodeChangeset.valueChange` carrying the revision bar

package/docs/main/repair-data.md

@@ -0,0 +1,275 @@
+# Repair Data
+
+This document offers a high-level view of our design choices regarding repair data.
+It should be updated once more progress is made on the implementation.
+
+## What is Repair Data
+
+In order to undo an edit `e` that was applied to state `s1` and yielded state `s2`,
+we need to construct an inverse edit `e⁻¹` that yields state `s1` when applied to state `s2`.
+Computing `e⁻¹` requires the following information:
+
+-   The original change to be undone
+-   Any document state that we wish to restore as part of the undo
+    but cannot derive from the the original change.
+
+This last bullet point may not be immediately obvious,
+but it is a critical issue.
+We may need to recover information about the state of the document before the change that we wish to undo
+because document changes can be destructive:
+
+-   Setting the value on a node erases information about the prior value of that node.
+-   Deleting a subtree erases information about the contents of that subtree.
+
+Such data cannot be derived solely from the original changeset to be undone.
+We refer to the information that is needed in addition to the original changeset as "repair data".
+
+## Three Contexts
+
+Repair data is used in three different contexts.
+
+### Rolling Back Local Transactions
+
+When a client needs to edit the document, it runs a command as part of a transaction.
+Commands are allowed to return a special value to communicate to the transaction code that the transaction should be aborted.
+When that happens, any edits that the command had already applied to the document state need to be rolled back.
+
+Rolling back changes could be achieved by editing a separate copy of the document during the transaction
+(possibly though a persistent data structure, or a copy on write system).
+The current implementation (which will likely change soon) edits the one true document state as the transaction progresses, and rolls back the changes afterward.
+It actually rolls back the changes even if the transaction succeeds,
+but that's not particularly relevant to our discussion.
+
+### Local Branch Updates
+
+When a client successfully completes a local transaction,
+it updates the local document state to reflect the impact of the edit,
+and it sends the edit to the service for sequencing.
+Under ideal circumstances, the next edit that the client receives from the service is that same edit that it had applied locally and sent for sequencing.
+If that's the case, the client does not need to update the document state.
+It's possible for an edit from a peer to be sequenced before the edit that was applied locally and sent out.
+When that happens,
+the local client needs to update the document state to reflect not only the impact of the edit from the peer,
+but also the impact that the peer edit has on the local edit.
+
+Consider the following example:
+
+-   Local edit: Delete nodes A and B iff A and B exist.
+-   Peer edit: Delete node A.
+
+If the peer edit is sequenced before the local edit,
+the rebased version of the local edit will have its constraint violated.
+This ought to leave the document in a state where A was deleted but B was not deleted.
+In order to arrive at such a state from the local tip state
+(where both A and B were deleted)
+it is necessary to revive node B.
+
+### User Undo
+
+This is the more obvious use case:
+undoing destructive operation requires the corresponding repair data.
+See the [undo design document](./undo.md) for more details.
+
+## Repair Data Stores
+
+Repair data is computed by each client as they apply changes to documents.
+For example, before deleting a subtree from the document,
+the client first takes note of the data in that subtree so that it can revive it later if need be.
+Until it is needed,
+or until it can be discarded,
+repair data is stored in a `RepairDataStore`.
+
+Each of the three contexts in which repair data may be needed maintains its own repair data store:
+
+### Rolling Back Local Transactions
+
+Each transaction uses a repair data store to keep track of the data destroyed during the transaction.
+This data is then pulled from the store when rolling back the transaction.
+Note: this may change soon.
+
+The repair data for transaction steps is discarded when the transaction is completed/aborted.
+
+### Local Branch Updates
+
+The local state manager uses a repair data store to keep track of the data destroyed by edits that have been applied locally but have yet to be sequenced.
+This data is then pulled from the store when concurrent edits cause the local edits to be rolled back as part of rebasing.
+
+The repair data for the local changes is discarded when the local changes are sequenced or rolled back as part of rebasing.
+
+### User Undo
+
+The `EditManager`, whose responsibilities include producing deltas in response to sequenced changes,
+needs to use a repair data store to keep track of the data destroyed by sequenced edits.
+This data is then pulled from the store to produce a delta when an undo edit is applied.
+
+The repair data for an individual edit in the trunk is discarded when the corresponding edit falls outside of the [undo window](./undo.md).
+
+## Characterizing Repair Data by Input Path
+
+In order to store repair data in a repair data store and be able to fetch it later,
+we need to establish a convention for unambiguously characterizing what data is being stored or fetched.
+
+The convention we have opted for is to characterize each deleted node
+(or deleted value on a node)
+by the path of the node in the input context of
+(i.e., the state prior to)
+the change that deleted the node (or its value).
+
+This has two consequences.
+
+### Computing Repair Data Per Individual Edit
+
+When first computing repair data for storage,
+one must compute it for the individual edit that next applies to the tip state,
+as opposed to computing it for a composed set of edits all at once.
+This is because the input context of a composed set of edits is
+different from the input context of the individual edits in the set
+(except for the first edit in the set).
+
+Depending on how much information was preserved in the composition of the edits,
+it may be possible to work out the correct path of the deleted data for each edit in a composed changeset.
+This would however be rather complicated,
+and would place restrictions on how lossy the composition could be,
+which in turn reduces the value of composing the edits in the first place.
+For example, document nodes that were inserted by an edit and deleted by the next may need to be preserved as part of the composition of these two edits.
+
+### Fetching Repair Data Before Rebasing
+
+Inverse edits sometimes need to be rebased.
+When that happens, the marks in the rebased changeset can shift to a different location.
+If we were to query a repair data store based on the path of a changeset mark that has been shifted due to rebasing,
+we would end up querying the store with the wrong path,
+which could lead to no repair data being found,
+or the wrong repair data being found.
+
+We avoid this issue by querying the repair data store for repair data based on the original inverse change
+(i.e., before any rebasing).
+
+Another alternative would be to record the original path within the changeset mark for which we need to request repair data,
+and use that path instead of the mark's path.
+This would however make such changeset marks more computationally expensive.
+It is tempting to think that such an approach would help avoid querying the repair data store for changeset marks that will end up being cancelled out.
+This line of thinking however does not take into account the fact that we do not want to cancel out such marks.
+For example, if a local change that deletes a node gets rebased,
+the revival of the deleted node and its deletion by the rebased local edit may ultimately cancel out in the delta being sent out to update the application state,
+but the repair data store needs to be updated to reflect that it is the rebased edit
+that performed the edit
+(which may now be occurring at different index).
+
+## Characterizing Repair Data by Tip-State Path
+
+This section documents an alternative way to characterize repair data.
+As such, **this section does not reflect how the system works**.
+
+Instead of characterizing repair data by its path in the document in the input context of the edit that deleted it,
+one can characterize by it by its path in the document's current (i.e., "tip") state.
+
+This makes some intuitive sense when considering that:
+
+-   The tip state is the _lingua franca_ of the rebase process: concurrent changesets are constantly reframed in terms of the tip state in order to be applied.
+-   The tip state forms the input context that inverse changes
+    (for which repair data needs to be fetched)
+    are applied to.
+    See [Fetching Repair Data Before Rebasing](#fetching-repair-data-before-rebasing).
+
+This approach however comes with some drawbacks:
+
+-   The repair store data would need to be updated (effectively, rebased) in the face of changes to keep the repair data in sync with the tip state.
+-   Representing the location of the repair data within the tip context requires a way to represent the position where the data would be if it were revived.
+    In optional and value fields this would mean all the repair data ends up in the same "slot".
+    In sequence fields the repair data would be represented as places with lineage in order to differentiate them.
+    Looking up repair data for a sequence field would require having an efficient way to sift thought all those places.
+    More generally speaking, this approach seems to require field-kind-specific code in order to characterize the repair data.
+    It is plausible that whatever field-kind-specific code is needed to accomplish this is also the same code that is needed for anchor management, but that has yet to be confirmed.
+    This may become clearer as we expand our anchor capabilities and make them field-kind specific.
+
+## Additional Considerations
+
+### Avoiding Step-by-Step Delta Application
+
+When a peer edit is received by a client
+the local state need to be updated to reflect that edit.
+When the client has local edits
+(i.e., edits that have been applied locally, but have yet to be sequenced)
+updating the local state involves a combination of undoing the local edits,
+applying the newly received peer edit,
+and applying the rebased version of the local edits.
+It is common for the rollback of the local edits to cancel out with the application of the rebased version of the local edits.
+This leads to a delta that is minimal
+(e.g., it doesn't involve inserting then deleting the same node).
+Applications tend to prefer such minimal updates as it reduces the amount of update work that they need to perform.
+
+Ensuring that we send minimal deltas to applications may seem at odds with the requirements outlined in
+[Computing Repair Data Per Individual Edit](#computing-repair-data-per-individual-edit).
+It need not be.
+We can decouple the computation of the repair data from the computation of the delta,
+the former being carried out per changeset and the later one per update.
+
+### Abstract Repair Data
+
+Repair data can exist in repair data stores, changesets, and deltas.
+Ultimately, repair data is consumed by the application when applying deltas.
+
+While we could encode repair data in the same concrete representation we use for inserted subtrees,
+doing so may force the application to translate the repair data from its own encoding into this concrete representation,
+only to translate it back into its own encoding when consuming the delta.
+It therefore seems preferable to allow the repair data encoding to be application specific by default,
+and only convert it to a concrete application-agnostic encoding when it needs to be sent over the wire
+(e.g., in summaries).
+This also allows for the repair data to be encoded as an opaque token that only the application code can match to document data.
+This opaque token encoding simplifies the contract around repair data:
+the token can be cheaply copied and it does not allow for the repair data to be read or mutated.
+
+### Deleting Revived Data
+
+It's possible for an edit to revive some subtree and delete a part of that same subtree.
+When that occurs, it is necessary for the repair data associated with that changeset to include the deleted portion of the revived tree.
+
+In such a scenario, we must be careful about how we characterize the repair data.
+A naive approach may lead to the same path used to characterize different repair data.
+
+For example, if a document contains a sequence of Point subtrees,
+and an edit revives the Point at the start of the sequence,
+then deletes the X node under the revived Point,
+while also deleting the X node under the first Point in the sequence,
+then the repair data for the deleted nodes may end up characterized as the same path ("points[0].x").
+
+A possible solution may be to characterize repair data by its path after all nodes have been revived,
+but before any nodes are inserted, deleted, or moved.
+It may also be possible to simply track paths to deleted revived content separately
+(e.g., using a boolean to indicate this special case).
+
+### Computing Repair Data From Changes vs. Deltas
+
+The advantage of computing repair data based on deltas as opposed to changes,
+is that deltas are not coupled to the details of `FieldKind` individual field kind implementations.
+
+In order to use deltas when computing repair data,
+we must ensure they preserve all the necessary information.
+This can be achieved by following two rules:
+
+1. Do not compute repair data based on deltas that represent composed changesets
+   (see [Computing Repair Data Per Individual Edit](#computing-repair-data-per-individual-edit)).
+2. Do not apply deletions to revived subtrees as part of the change-to-delta conversion.
+
+Interestingly, #2 is not possible if we follow the [Abstract Repair Data](#abstract-repair-data) approach.
+
+### Repair Data Flow
+
+While the [three contexts](#three-contexts) in which repair data exists operate independently,
+it is interesting to consider how repair data effectively flows between them:
+
+-   Repair data from a successful transaction is dropped along with the transaction's repair data store.
+    Equivalent repair data is added to the local branch's repair store.
+-   Repair data from a local edit that gets rebased is dropped from the local branch's repair store.
+    Repair data from the rebased version of that local edit is added to the local branch's repair store.
+-   Repair data from a local edits that is sequenced is dropped from the local branch's repair store.
+    Equivalent repair data is added to the trunk's repair store.
+-   Repair data from a sequenced edit is dropped from the trunk's repair store when that edit falls outside of the undo window.
+
+It is tempting to build efficient pathways for the repair data flow from one repair data store to the next without being fully re-computed:
+
+-   A more direct transition of the repair data from the transaction to the local branch is currently impractical because the repair data of the transaction is based on a sequence of atomic changes instead of the unified changeset that makes it to the local branch.
+    Future iterations of the transaction code may remove this barrier but may also remove the need for repair data in the transaction code altogether.
+-   The repair data that flows out and back into the local branch repair data store as local edits get rebased may be hard to optimize because the repair data of the rebased edit may be subtly different from that of the non-rebased one.
+-   A more direct transition fom the local branch store to the trunk store seems possible.