Currently, every array or map are stored in its own slab and
parent slab refers to child array or map by SlabID.

The current approach can lead to many small slabs, especially for
Cadence data structures with multiple nested levels.

This commit inlines child array/map in parent slab when:
- child array/map fits in one slab (root slab is data slab)
- encoded size of inlined child array/map is less than the
  max inline size limit enforced by parent

This commit optimizes encoding size by:
- reusing inlined array types
- reusing seed, digests, and field names of inlined composite types

Also update debugging code to handle inlined array/map element.

Currently, in parentUpdater callback, parent array/map resets same
child value.

Child value ID should match overwritten SlabIDStorable
or Slab.SlabID().

This commit adds check to make sure same child value is being reset.

This commit adds callback notification in the set or inserted child
element in array.  So if child element is modified after Array.Set()
or Array.Insert(), changes to child element is properly reflected
in the parent array.

This commit doesn't appear to be needed by current version of Cadence
but it helps reduce Atree's dependence on an implementation detail
of Cadence.

This commit adds callback notification in the set child element in map.
So if child element is modified after OrderedMap.Set() , changes to
child element is properly reflected in the parent map.

This commit doesn't appear to be needed by current version of Cadence
but it helps reduce Atree's dependence on an implementation detail
of Cadence.

Currently, deduplication feature in PR 342 (not merged yet)
does not support Cadence attachments.

Add support for Cadence attachments and other future
use cases by using type ID and sorted field names
instead of field count.

While at it, also refactor encoding composite type to
reduce traversal and type assertion.

Decoded ExtraData (including TypeInfo) can be shared by all
inlined slabs.  This commit creates a new ExtraData with copied
TypeInfo for inlined slabs to prevent accidental mutation.

Decoded ExtraData (including keys) can be shared by all
inlined composite referring to the same type.

This commit copies key for inlined composite to prevent
accidental mutation.

Some of the comments were taken from Atree's README
which was originally authored by Ramtin.

Co-authored-by: Ramtin M. Seraj <[email protected]>

While at it, also refactored validMapSlab().

While at it, also refactored validArraySlab().

Currently, ValidArray() doesn't verify that inlined array slabs
are in not storage.

It is called by tests in Atree and Cadence, so update it
to check if inlined array slabs are in storage.

This change:
- Adds ReadOnly iterators that match current iterator API
  (except for the "ReadOnly" suffix added to some function names).
- Refactors API of non-Readonly iterators because register
  inlining will require more parameters for MapIterator.

For ReadOnly iterators, the caller is responsible for preventing
changes to child containers during iteration because mutations
of child containers are not guaranteed to persist.

For non-ReadOnly iterators, two additional parameters are needed to
update child container in parent map when child container is modified.

Currently, Set() and Remove() return overwritten or removed storable.
If storable is inlined slab, it is not stored in storage (because it
is removed from its parent slab which is in storage), so any future
changes to it would be lost.

On the other hand, if overwritten or removed storable is SlabIDStorable,
any future changes to it can still be persisted because it is in
its own slab in storage.

This inconsistency (not merged or deployed yet) can cause potential
data loss or unexpected behavior if deployed.

This commit uninlines inlined slabs that is overwritten or removed,
stores them in storage, and returns their SlabID as storable to caller.

This commit prunes Array.mutableElementIndex by:
- deleting overwritten element from mutableElementIndex
- deleting removed element from mutableElementIndex

While at it, add more checks for index in mutableElementIndex:
- can't exceed number of array elements
- can't be less than 0

For context, Array.mutableElementIndex contains mutable
element's updated index in parent array.  When parent
array is modified, index in mutableElementIndex is updated.

This commit checks if child is in parent container at adjusted index or
under the same key in parentUpdater() before modifying parent container.

If child is no longer part of parent, parentUpdater() returns with no-op,
and this callback is set to nil.

This is to handle outdated child reference modifying parent after it
is removed.

Previously, the constant expression used hardcoded numbers.

Currently, Atree uses CBOR tag numbers [247, 255] and grows downwards.
Cadence uses CBOR tag numbers [128, 224] and grows upwards.  There
MUST not be any overlap.

This commit adds comment to warning about overlapping.  We can be more
proactive about this by dividing up the remaining available tag numbers
between Cadence and Atree.

NOTE: A similar comment will be added to Cadence repo at
github.com/onflow/cadence when the next atree-cadence integration
PR is opened.

This commit adds an extra check in exported validation functions
that are only used for tests in Atree but can also be used by Cadence.

…omparator-and-hashinputprovider-to-mapiterator

…ashinputprovider-to-mapiterator

Add readonly iterators and support value mutations only from non-readonly iterators

Inline child array and map data slab into parent slab

This commit adds flag "slabcheck" to enable checking in-memory
and serialized slabs.  This flag is off by default because it can
take a long time to run.

This commit smoke tests mutation of child container:
- existing child retrieved from parent array/map
- new child appened/inserted to parent array
- existing child set in parent array/map
- new child set in parent map

…rray-map-inlining

Update smoke test for atree inlining

Some errors that should be returned as external error
are being returned as fatal error.  This caused a
problem that was detected during Cadence integration.

This commit resolves the problem by returning these
fatal errors as external errors.

Some errors that should be returned as external error
are being returned as fatal error.  This caused a
problem that was detected during Cadence integration.

This commit resolves the problem by returning these
fatal errors as external errors.

Cadence integration requires InlinedExtraData interface.

ContainerStorable interface supports encoding container storable
(storable containing other storables) as element.  This is needed
for integration with Cadence.

This is needed for integration with Cadence because map key can be
Cadence enums.

Update for Cadence integration for atree inlining and deduplication

…moke-test

Make smoke tests check recently added data deduplication feature

Currently, EncodeAsElement is used to encode inlined array and map,
while Encode is used to encode standalone array and map.

This commit simplifies encoding API by using Encode() to encode
both inlined/standalone array/map.

This commit makes StorableSlab.Encode() return
error if it contains inlined array or inlined map.

Remove ContainerStorable.EncodeAsElement

Mutable iterator for array and map supports:
- indirect element mutation, such as modifying nested container
- direct element mutation, such as overwriting existing element
  with new element

Mutable iterator for array and map doesn't support:
- inserting new elements into the array/map
- removing existing elements from the array/map

NOTE: use readonly iterator if mutation is not needed for
better performance.

This commit:
- adds new interfaces ArrayIterator and MapIterator
- decouples implementation of mutable and readonly iterators
- refactors related functions