Package com.google.genkit.ai.agent.internal

Class SnapshotSharding

java.lang.Object

com.google.genkit.ai.agent.internal.SnapshotSharding

public final class SnapshotSharding
extends Object

Pure, backend-agnostic sharding / checkpoint / RFC-6902 reconstruction helpers shared by the Firestore, DynamoDB, and Cosmos DB session stores.

Session stores that use the sharded checkpoint + diff + pointer layout persist a session's state as a periodic full "checkpoint" (its JSON split into byte-sized shards) plus a chain of RFC-6902 "diff" patches from the nearest checkpoint. These helpers implement the pure logic of that scheme so every backend behaves identically:

• shouldCheckpoint(boolean, int, int, int, int) — decides checkpoint vs diff for a new snapshot.
• shardString(java.lang.String, int) / reassembleShards(java.util.List<java.lang.String>) — byte-exact splitting/rejoining of the checkpoint JSON.
• reconstructState(java.lang.String, java.util.List<java.lang.String>) — replays the checkpoint + ordered diffs back into a state node.
• validateId(java.lang.String) — validates snapshot/session identifiers.

Method Summary

Modifier and Type	Method	Description
static String	reassembleShards(List<String> shards)	Reassembles shards produced by shardString(java.lang.String, int) back into the original string.
static com.fasterxml.jackson.databind.JsonNode	reconstructState(String checkpointJson, List<String> diffPatchesJson)	Reconstructs a state node from a checkpoint JSON string and a list of RFC-6902 patch JSON strings, applied in order via JsonPatch.apply(com.fasterxml.jackson.databind.JsonNode, com.fasterxml.jackson.databind.JsonNode).
static List<String>	shardString(String value, int shardSize)	Splits a UTF-8 string into shards of at most shardSize bytes each.
static boolean	shouldCheckpoint(boolean parentExists, int depthFromCheckpoint, int checkpointInterval, int diffSizeBytes, int shardSize)	Decides whether to write a full checkpoint instead of a diff.
static void	validateId(String id)	Validates a snapshot/session document id.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

shouldCheckpoint

public static boolean shouldCheckpoint(boolean parentExists,
 int depthFromCheckpoint,
 int checkpointInterval,
 int diffSizeBytes,
 int shardSize)

Decides whether to write a full checkpoint instead of a diff.

A checkpoint is written when:

• there is no usable parent (session root, or parent orphaned/missing); or
• the depth from the nearest checkpoint reaches checkpointInterval; or
• the diff against the parent would exceed shardSize bytes.

Parameters:

parentExists - whether a usable parent snapshot exists

depthFromCheckpoint - the number of diffs (inclusive) that would separate this snapshot from its nearest checkpoint

checkpointInterval - the configured checkpoint interval

diffSizeBytes - the serialized size of the candidate diff in bytes

shardSize - the configured shard size in bytes

Returns:

true if a full checkpoint should be written

shardString

public static List<String> shardString(String value,
 int shardSize)

Splits a UTF-8 string into shards of at most shardSize bytes each.

Sharding is byte-exact: shards are concatenated by raw bytes (not chars) so multi-byte UTF-8 sequences split across a boundary reassemble correctly.

Parameters:

value - the string to shard

shardSize - the maximum shard size in bytes (must be >= 1)

Returns:

the ordered shards; each shard holds at most shardSize raw UTF-8 bytes encoded as an ISO-8859-1 string (1 char per byte) for byte-exact reassembly by reassembleShards(java.util.List<java.lang.String>)

reassembleShards

public static String reassembleShards(List<String> shards)

Reassembles shards produced by shardString(java.lang.String, int) back into the original string.

Parameters:

shards - the ordered shard list

Returns:

the reassembled original string

reconstructState

public static com.fasterxml.jackson.databind.JsonNode reconstructState(String checkpointJson,
 List<String> diffPatchesJson)
                                                                throws Exception

Reconstructs a state node from a checkpoint JSON string and a list of RFC-6902 patch JSON strings, applied in order via JsonPatch.apply(com.fasterxml.jackson.databind.JsonNode, com.fasterxml.jackson.databind.JsonNode).

Parameters:

checkpointJson - the full checkpoint state JSON

diffPatchesJson - the ordered list of opaque JSON-string patches (each an RFC-6902 op array)

Returns:

the reconstructed state node

Throws:

Exception - if any JSON cannot be parsed

validateId

public static void validateId(String id)

Validates a snapshot/session document id.

Parameters:

id - the id to validate

Throws:

GenkitException - with INVALID_ARGUMENT if the id is null, empty, or contains a forward slash