/*!
 * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
 * Licensed under the MIT License.
 */
import type { IFluidHandle } from "@fluidframework/core-interfaces";
import type { IChannelStorageService } from "@fluidframework/datastore-definitions/internal";
import type { IExperimentalIncrementalSummaryContext } from "@fluidframework/runtime-definitions/internal";
import { SummaryTreeBuilder } from "@fluidframework/runtime-utils/internal";
import type { ITreeCursorSynchronous } from "../../core/index.js";
import type { SummaryElementStringifier } from "../../shared-tree-core/index.js";
import { type JsonCompatible } from "../../util/index.js";
import type { ChunkReferenceId, EncodedFieldBatchV2, IncrementalEncoderDecoder, IncrementalEncodingPolicy, TreeChunk } from "../chunked-forest/index.js";
/**
 * The behavior of the forest's incremental summary - whether the summary should be a single blob or incremental.
 */
export declare enum ForestIncrementalSummaryBehavior {
    /**
     * The forest can encode chunks incrementally, i.e., chunks that support incremental encoding will be encoded
     * separately - they will be added to a separate tree.
     * The incremental summary format is described in {@link ForestIncrementalSummaryBuilder}.
     */
    Incremental = 0,
    /**
     * The forest should encode all of it's data in a single summary blob.
     * @remarks
     * The format of the summary will be the same as the old format (pre-incremental summaries) and is fully
     * backwards compatible with the old format. The summary will basically look like an incremental summary
     * with no incremental fields - it will only contain the "ForestTree" blob in the summary format described
     * in {@link ForestIncrementalSummaryBuilder}.
     */
    SingleBlob = 1
}
/**
 * Tracks and builds the incremental summary tree for a forest where chunks that support incremental encoding are
 * stored in a separate tree in the summary under its {@link ChunkReferenceId}.
 * The summary tree for a chunk is self-sufficient and can be independently loaded and used to reconstruct the
 * chunk's contents without any additional context from its parent.
 *
 * An example summary tree with incremental summary:
 *     Forest
 *     ├── contents
 *     ├── 0
 *     |   ├── contents
 *     |   ├── 1
 *     |   |   ├── contents
 *     |   |   ├── 2
 *     |   |   |   ├── contents
 *     |   ├── 3 - ".../Forest/ForestTree/0/1/3"
 *     ├── 4
 *     |   ├── contents
 *     |   ├── ...
 *     ├── 5 - "/.../Forest/ForestTree/5"
 * - Forest is a summary tree node added by the shared tree and contains the following:
 *   - The inline portion of the top-level forest content is stored in a summary blob called "contents".
 *     It also contains the {@link ChunkReferenceId}s of the incremental chunks under it.
 *   - The summary for each incremental chunk under it is stored against its {@link ChunkReferenceId}.
 * - For each chunk, the structure of the summary tree is the same as the Forest. It contains the following:
 *   - The inline portion of the chunk content is stored in a blob called "contents".
 *     It also contains the {@link ChunkReferenceId}s of the incremental chunks under it.
 *   - The summary for each incremental chunk under it is stored against its {@link ChunkReferenceId}.
 * - Chunks that do not change between summaries are summarized as handles in the summary tree.
 *
 * TODO: AB#46752
 * Add strong types for the summary structure to document it better. It will help make it super clear what the actual
 * format is in a way that can easily be linked to, documented and inspected.
 */
export declare class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecoder {
    private readonly enableIncrementalSummary;
    private readonly getChunkAtCursor;
    readonly shouldEncodeIncrementally: IncrementalEncodingPolicy;
    private readonly initialSequenceNumber;
    /**
     * The next reference ID to use for a chunk.
     */
    private nextReferenceId;
    /**
     * For a given summary sequence number, keeps track of a chunk's properties that will be used to generate
     * a summary handle for the chunk if it does not change between summaries.
     *
     * @remarks
     * `chunk` (the TreeChunk object) is used as the map key by object identity.
     * This assumes each chunk appears at exactly one position in the forest — an invariant that holds because every
     * node in a tree has a single parent.
     * If the forest ever introduced structural sharing (two positions backed by the same TreeChunk object),
     * a second call here would silently overwrite the first entry, causing the first position's handle to point
     * to the second position's parent in subsequent summaries. In theory, this should be fine from summary perspective
     * because the chunk contents are the same. But, it could lead to confusing handle paths in the summary tree and
     * may lead to other unexpected behavior. Adequate tests should be added if structural sharing is introduced.
     */
    private readonly chunkTrackingPropertiesMap;
    /**
     * True when encoding a summary, false otherwise.
     * @remarks
     * Exposed for testing purposes.
     */
    get isSummarizing(): boolean;
    /**
     * The sequence number of the latest summary that was successful.
     */
    private latestSummarySequenceNumber;
    /**
     * The current state of the summary being "tracked".
     * @remarks
     * A summary being "tracked" means that a summary is being encoded.
     * This is undefined if no summary is currently being encoded.
     *
     * @privateRemarks
     * This has nothing to do which how content from a summary being loaded is tracked (thats written all in chunkTrackingPropertiesMap).
     * "Tracked" should probably be renamed to "encoded" or "summarizing" or something like that to avoid confusion.
     * Perhaps a better way to clarify this would be to not store this property on this object at all, and have it
     * only exist within the scope of the summary encoding (use an encoding specific object to accumulate any stat necessary during encode).
     */
    private trackedSummaryProperties;
    /**
     * A map of chunk reference IDs to their encoded contents. This is typically used during the loading of the
     * forest to retrieve the contents of the chunks that were summarized incrementally.
     */
    /**
     * A map of chunk reference IDs to their {@link ChunkLoadProperties}.
     * This is used during the loading of the forest to track each chunk that is retrieved and decoded.
     */
    private readonly loadedChunksMap;
    constructor(enableIncrementalSummary: boolean, getChunkAtCursor: (cursor: ITreeCursorSynchronous) => TreeChunk[], shouldEncodeIncrementally: IncrementalEncodingPolicy, initialSequenceNumber: number);
    /**
     * Must be called when the forest is loaded to download the encoded contents of incremental chunks.
     * @param services - The channel storage service to use to access the snapshot tree and download the
     * contents of the chunks.
     * @param readAndParse - A function that reads and parses a blob from the storage service.
     */
    load(args: {
        services: IChannelStorageService;
        readAndParseChunk: (chunkBlobPath: string) => Promise<JsonCompatible<IFluidHandle>>;
    }): Promise<void>;
    /**
     * Asserts that a summary is currently being tracked and that the tracked summary properties are defined.
     * @returns The properties of the tracked summary.
     */
    private requireTrackingSummary;
    /**
     * Must be called when starting a new forest summary to track it.
     * @param fullTree - Whether the summary is a full tree summary. If true, the summary will not contain
     * any summary handles. All chunks must be summarized in full.
     * @param incrementalSummaryContext - The context for the incremental summary that contains the sequence numbers
     * for the current and latest summaries.
     * @param stringify - Serializes content (including {@link (IFluidHandle:interface)}s) for adding to a summary blob.
     * @returns the behavior of the forest's incremental summary.
     */
    startSummary(args: {
        fullTree: boolean;
        incrementalSummaryContext: IExperimentalIncrementalSummaryContext | undefined;
        stringify: SummaryElementStringifier;
        builder: SummaryTreeBuilder;
    }): ForestIncrementalSummaryBehavior;
    /**
     * Computes a chunk's path in the latest summary by traversing up the parent chain via
     * {@link latestSummaryRefIdMap}.
     *
     * Each {@link ChunkSummaryProperties.parentReferenceId} points to the chunk's parent as it
     * appeared in the summary where the entry was last written. Walking up the chain from the
     * chunk to the root produces the full path that can be used in a summary handle path.
     */
    private computeHandlePathInLatestSummary;
    /**
     * {@link IncrementalEncoder.encodeIncrementalField}
     * @remarks Returns an empty array if the field has no content.
     */
    encodeIncrementalField(cursor: ITreeCursorSynchronous, chunkEncoder: (chunk: TreeChunk) => EncodedFieldBatchV2): ChunkReferenceId[];
    /**
     * Must be called after summary generation is complete to finish tracking the summary.
     * It clears any tracking state and deletes the tracking properties for summaries that are older than the
     * latest successful summary.
     * @param incrementalSummaryContext - The context for the incremental summary that contains the sequence numbers.
     * If this is undefined, the summary tree will only contain a summary blob for `forestSummaryRootContent`.
     * @param forestSummaryRootContent - The stringified ForestCodec output of top-level Forest content.
     * @param forestSummaryRootContentKey - The key to use for the blob containing `forestSummaryRootContent`.
     * @param builder - The summary tree builder to use to add the forest's contents. Note that if tracking an incremental
     * summary, this builder will be the same as the one tracked in `trackedSummaryProperties`.
     * @returns the Forest's summary tree.
     */
    completeSummary(args: {
        incrementalSummaryContext: IExperimentalIncrementalSummaryContext | undefined;
        forestSummaryRootContent: string;
        forestSummaryRootContentKey: string;
        builder: SummaryTreeBuilder;
    }): void;
    /**
     * {@link IncrementalEncoder.decodeIncrementalChunk}
     */
    decodeIncrementalChunk(referenceId: ChunkReferenceId, chunkDecoder: (encoded: EncodedFieldBatchV2) => TreeChunk): TreeChunk;
}
//# sourceMappingURL=incrementalSummaryBuilder.d.ts.map