@dudousxd/nestjs-agent-rag 0.7.0 → 0.9.0

package/dist/index.d.cts

@@ -5,6 +5,31 @@ interface ChunkOptions {
     chunkSize?: number;
     /** Characters of overlap carried from the end of one chunk into the next. Default 100. */
     overlap?: number;
+    /**
+     * Treat the text as records joined by this string, and never split one across chunks.
+     *
+     * Default chunking is structure-blind: it breaks at the *latest* paragraph/sentence/word boundary
+     * in the window, which for record-shaped text means a cut lands mid-record routinely. That is fine
+     * for prose, where the two halves are still sentences. It is not fine for a table flattened to one
+     * record per row, because the half that keeps the row identifier and the half that keeps the value
+     * end up in different chunks, and neither can answer a question about that row on its own.
+     *
+     * With a separator set, whole records are packed greedily up to `chunkSize` and a record is never
+     * cut — except one longer than `chunkSize`, which has nowhere to go and is character-split as
+     * usual, since no chunker can avoid that.
+     *
+     * `overlap` is IGNORED in this mode, deliberately. Overlap exists to rescue a sentence that a
+     * boundary cut in half; a boundary that never falls inside a record has nothing to rescue, and
+     * carrying the tail of the previous chunk in would duplicate whole records into neighbouring chunks
+     * — paying for the same rows twice at embedding time and letting one row match from two places.
+     *
+     * Measured on a 200-row spreadsheet flattened to one field-labelled record per row (15 columns,
+     * ~800-char budget): blind chunking left 27% of records split, and on questions targeting a field
+     * on the far side of such a cut, BM25 answered 54/66 (MRR 0.818) against 66/66 (MRR 1.000) with
+     * records kept whole. The dense leg scored 7/66 either way — 200 near-identical rows produce
+     * near-identical vectors, so that leg cannot do row lookup at all and chunking does not change it.
+     */
+    separator?: string;
 }
 /**
  * Splits text into overlapping chunks for embedding. Greedy up to `chunkSize`, but prefers to break
@@ -149,6 +174,32 @@ interface VectorStore {
      * `size` changed), or {@link VectorStore.remove remove} (orphaned).
      */
     listDocuments(filter?: Record<string, unknown>): Promise<IndexedDocument[]>;
+    /**
+     * Read one document's chunks back — id, text, metadata — ordered by their position in the
+     * document, optionally paged with `limit`/`offset`.
+     *
+     * The gap this closes is that **the text a store holds is otherwise write-only**. Every other way
+     * back to it is a ranked query: {@link VectorStore.search} needs an embedding,
+     * {@link LexicalVectorStore.searchText} needs a query string, and both return whatever *matched*,
+     * in relevance order, capped at `topK`. Neither can answer "show me what was indexed for this
+     * document, in order" — the question you ask when retrieval returns the wrong passage and you need
+     * to know whether the chunker cut badly or the retriever chose badly. Without this, the only way to
+     * see stored text is to reach around the adapter into the backing engine, which is exactly the
+     * abstraction break a consumer adopts a store to avoid.
+     *
+     * Document-scoped rather than filter-scoped, matching {@link VectorStore.remove} and
+     * {@link VectorStore.updateMetadata}: ordering is the whole point, and "position within the
+     * document" is only meaningful once a document has been picked. Enumerate documents with
+     * {@link VectorStore.listDocuments} first when you need to sweep.
+     *
+     * An unknown `documentId` yields `[]`; it does not throw, matching `remove` and `updateMetadata`.
+     *
+     * NOT an access-control seam. It takes no metadata `filter` and applies none, so it cannot enforce
+     * one — a caller that gates retrieval on a metadata field (tenant, audience, collection) MUST
+     * resolve that gate itself before calling, exactly as it would before `remove`. It is deliberately
+     * shaped for an operator/debug surface, not for serving end users.
+     */
+    listChunks(documentId: string, options?: ListChunksOptions): Promise<StoredChunk[]>;
     /**
      * The distinct source document ids currently indexed, optionally narrowed by a metadata `filter` —
      * {@link VectorStore.listDocuments} without the metadata. Use it when you only need the id set (a
@@ -246,6 +297,25 @@ interface IndexedDocument {
     id: string;
     metadata?: Record<string, unknown>;
 }
+/** One stored chunk, read back verbatim — what {@link VectorStore.listChunks} yields. */
+interface StoredChunk {
+    /** The chunk id: `${documentId}#<n>`, or the bare document id for a single-chunk document. */
+    id: string;
+    /** Zero-based position within the document, parsed from the id. A bare id is chunk `0`. */
+    index: number;
+    /** The chunk text as it was indexed — the exact string the embedding was computed from. */
+    text: string;
+    metadata?: Record<string, unknown>;
+}
+/** Paging for {@link VectorStore.listChunks}. Omit both to read the whole document. */
+interface ListChunksOptions {
+    /** Max chunks to return, applied after ordering by {@link StoredChunk.index}. */
+    limit?: number;
+    /** Chunks to skip, applied after ordering. */
+    offset?: number;
+}
+/** Chunk `n` of `${documentId}#<n>`; a bare document id (single-chunk document) is `0`. */
+declare function chunkIndexOf(chunkId: string): number;
 /** Collapse a chunk id (`${documentId}#<n>`) back to its source document id. */
 declare function documentIdOf(chunkId: string): string;
 
@@ -271,6 +341,16 @@ declare class MemoryVectorStore implements VectorStore {
      */
     updateMetadata(documentId: string, patch: MetadataPatch): Promise<number>;
     listDocuments(filter?: Record<string, unknown>): Promise<IndexedDocument[]>;
+    /**
+     * The chunks of one document, in document order. See {@link VectorStore.listChunks}.
+     *
+     * Insertion order is not document order — `upsert` stores whatever the caller passed, and a
+     * re-ingest that rewrites chunk 3 alone moves it to the end of the Map. So this sorts by the index
+     * parsed from the id, the same thing the SQL and Redis adapters order by, rather than trusting the
+     * Map. A reference adapter that returned "usually ordered" would let a consumer ship a bug that
+     * only shows up on the store tests are NOT written against.
+     */
+    listChunks(documentId: string, options?: ListChunksOptions): Promise<StoredChunk[]>;
     listDocumentIds(filter?: Record<string, unknown>): Promise<string[]>;
     removeMany(documentIds: string[]): Promise<void>;
     /**
@@ -349,6 +429,19 @@ declare class PgVectorStore implements VectorStore {
      */
     updateMetadata(documentId: string, patch: MetadataPatch): Promise<number>;
     listDocuments(filter?: Record<string, unknown>): Promise<IndexedDocument[]>;
+    /**
+     * The chunks of one document, in document order. See {@link VectorStore.listChunks}.
+     *
+     * The order is computed from the id rather than stored: `#12` must sort after `#2`, which a plain
+     * `ORDER BY id` gets wrong on every document past ten chunks because it compares text. So the
+     * trailing number is extracted and cast to `int`, and a bare id (a single-chunk document, which
+     * carries no `#n` suffix) collapses to `0` — the same rule `chunkIndexOf` applies in the other two
+     * adapters.
+     *
+     * `embedding` is left out of the projection: it is the widest column in the table and useless to a
+     * caller reading text back.
+     */
+    listChunks(documentId: string, options?: ListChunksOptions): Promise<StoredChunk[]>;
     /** {@link listDocuments} without the metadata: one `DISTINCT` over the derived document id. */
     listDocumentIds(filter?: Record<string, unknown>): Promise<string[]>;
     /** N documents in one statement — the set-based form of {@link PgVectorStore.remove}. */
@@ -525,6 +618,25 @@ declare class RedisVectorStore implements LexicalVectorStore {
      * document owns. The glob is escaped so `gone` does not reach into `goner#0`.
      */
     private chunkKeys;
+    /**
+     * The chunks of one document, in document order. See {@link VectorStore.listChunks}.
+     *
+     * Reads the hashes directly (`HMGET text metadata_json`) rather than going through `FT.SEARCH`.
+     * Two reasons, and the second is the one that matters: the query language has no way to ask for
+     * "every chunk of this document" — `id` is the key name, not an indexed field — and `FT.SEARCH`
+     * caps at `LIMIT`, so paging a document through it would mean ordering by a field the index does
+     * not hold. `chunkKeys` is the same enumeration {@link RedisVectorStore.remove} and
+     * {@link RedisVectorStore.updateMetadata} already use, so "the chunks this returns" and "the chunks
+     * a delete would take" cannot drift apart.
+     *
+     * It inherits that method's cost too: one keyspace `SCAN` per call. Acceptable here because this
+     * is an inspection path (one document, on demand) and not something retrieval runs — but it is why
+     * this must not be put on a hot path or called in a loop over a corpus.
+     *
+     * `embedding` is deliberately not fetched: it is by far the largest field on the hash and nothing
+     * a caller reading text back can do with it.
+     */
+    listChunks(documentId: string, options?: ListChunksOptions): Promise<StoredChunk[]>;
     listDocuments(filter?: Record<string, unknown>): Promise<IndexedDocument[]>;
     /**
      * The id-only half of {@link RedisVectorStore.listDocuments}, served by `FT.SEARCH … NOCONTENT`:
@@ -843,4 +955,4 @@ interface RetrievalTool {
  */
 declare function createRetrievalTool(retriever: Retriever, options?: RetrievalToolOptions): RetrievalTool;
 
-export { type ChunkOptions, type ChunkRecord, EmbeddingRetriever, type EmbeddingRetrieverOptions, FilteredRetriever, HybridRetriever, type HybridRetrieverOptions, type IndexedDocument, type IngestChunksOptions, type IngestDocument, type IngestOptions, KeywordRetriever, type KeywordRetrieverOptions, LexicalRetriever, type LexicalVectorStore, MemoryVectorStore, type MetadataPatch, type PgClient, PgVectorStore, type PgVectorStoreOptions, type RedisSearchClient, RedisVectorSchemaMismatchError, RedisVectorStore, type RedisVectorStoreOptions, RerankingRetriever, type RerankingRetrieverOptions, type RetrievalTool, type RetrievalToolOptions, UnsafeRemovalError, type VectorRecord, type VectorSearchOptions, type VectorStore, applyMetadataPatch, chunkDocuments, chunkText, createRetrievalTool, documentIdOf, ingestChunks, ingestDocuments, isLexicalVectorStore };
+export { type ChunkOptions, type ChunkRecord, EmbeddingRetriever, type EmbeddingRetrieverOptions, FilteredRetriever, HybridRetriever, type HybridRetrieverOptions, type IndexedDocument, type IngestChunksOptions, type IngestDocument, type IngestOptions, KeywordRetriever, type KeywordRetrieverOptions, LexicalRetriever, type LexicalVectorStore, type ListChunksOptions, MemoryVectorStore, type MetadataPatch, type PgClient, PgVectorStore, type PgVectorStoreOptions, type RedisSearchClient, RedisVectorSchemaMismatchError, RedisVectorStore, type RedisVectorStoreOptions, RerankingRetriever, type RerankingRetrieverOptions, type RetrievalTool, type RetrievalToolOptions, type StoredChunk, UnsafeRemovalError, type VectorRecord, type VectorSearchOptions, type VectorStore, applyMetadataPatch, chunkDocuments, chunkIndexOf, chunkText, createRetrievalTool, documentIdOf, ingestChunks, ingestDocuments, isLexicalVectorStore };

package/dist/index.d.ts

@@ -5,6 +5,31 @@ interface ChunkOptions {
     chunkSize?: number;
     /** Characters of overlap carried from the end of one chunk into the next. Default 100. */
     overlap?: number;
+    /**
+     * Treat the text as records joined by this string, and never split one across chunks.
+     *
+     * Default chunking is structure-blind: it breaks at the *latest* paragraph/sentence/word boundary
+     * in the window, which for record-shaped text means a cut lands mid-record routinely. That is fine
+     * for prose, where the two halves are still sentences. It is not fine for a table flattened to one
+     * record per row, because the half that keeps the row identifier and the half that keeps the value
+     * end up in different chunks, and neither can answer a question about that row on its own.
+     *
+     * With a separator set, whole records are packed greedily up to `chunkSize` and a record is never
+     * cut — except one longer than `chunkSize`, which has nowhere to go and is character-split as
+     * usual, since no chunker can avoid that.
+     *
+     * `overlap` is IGNORED in this mode, deliberately. Overlap exists to rescue a sentence that a
+     * boundary cut in half; a boundary that never falls inside a record has nothing to rescue, and
+     * carrying the tail of the previous chunk in would duplicate whole records into neighbouring chunks
+     * — paying for the same rows twice at embedding time and letting one row match from two places.
+     *
+     * Measured on a 200-row spreadsheet flattened to one field-labelled record per row (15 columns,
+     * ~800-char budget): blind chunking left 27% of records split, and on questions targeting a field
+     * on the far side of such a cut, BM25 answered 54/66 (MRR 0.818) against 66/66 (MRR 1.000) with
+     * records kept whole. The dense leg scored 7/66 either way — 200 near-identical rows produce
+     * near-identical vectors, so that leg cannot do row lookup at all and chunking does not change it.
+     */
+    separator?: string;
 }
 /**
  * Splits text into overlapping chunks for embedding. Greedy up to `chunkSize`, but prefers to break
@@ -149,6 +174,32 @@ interface VectorStore {
      * `size` changed), or {@link VectorStore.remove remove} (orphaned).
      */
     listDocuments(filter?: Record<string, unknown>): Promise<IndexedDocument[]>;
+    /**
+     * Read one document's chunks back — id, text, metadata — ordered by their position in the
+     * document, optionally paged with `limit`/`offset`.
+     *
+     * The gap this closes is that **the text a store holds is otherwise write-only**. Every other way
+     * back to it is a ranked query: {@link VectorStore.search} needs an embedding,
+     * {@link LexicalVectorStore.searchText} needs a query string, and both return whatever *matched*,
+     * in relevance order, capped at `topK`. Neither can answer "show me what was indexed for this
+     * document, in order" — the question you ask when retrieval returns the wrong passage and you need
+     * to know whether the chunker cut badly or the retriever chose badly. Without this, the only way to
+     * see stored text is to reach around the adapter into the backing engine, which is exactly the
+     * abstraction break a consumer adopts a store to avoid.
+     *
+     * Document-scoped rather than filter-scoped, matching {@link VectorStore.remove} and
+     * {@link VectorStore.updateMetadata}: ordering is the whole point, and "position within the
+     * document" is only meaningful once a document has been picked. Enumerate documents with
+     * {@link VectorStore.listDocuments} first when you need to sweep.
+     *
+     * An unknown `documentId` yields `[]`; it does not throw, matching `remove` and `updateMetadata`.
+     *
+     * NOT an access-control seam. It takes no metadata `filter` and applies none, so it cannot enforce
+     * one — a caller that gates retrieval on a metadata field (tenant, audience, collection) MUST
+     * resolve that gate itself before calling, exactly as it would before `remove`. It is deliberately
+     * shaped for an operator/debug surface, not for serving end users.
+     */
+    listChunks(documentId: string, options?: ListChunksOptions): Promise<StoredChunk[]>;
     /**
      * The distinct source document ids currently indexed, optionally narrowed by a metadata `filter` —
      * {@link VectorStore.listDocuments} without the metadata. Use it when you only need the id set (a
@@ -246,6 +297,25 @@ interface IndexedDocument {
     id: string;
     metadata?: Record<string, unknown>;
 }
+/** One stored chunk, read back verbatim — what {@link VectorStore.listChunks} yields. */
+interface StoredChunk {
+    /** The chunk id: `${documentId}#<n>`, or the bare document id for a single-chunk document. */
+    id: string;
+    /** Zero-based position within the document, parsed from the id. A bare id is chunk `0`. */
+    index: number;
+    /** The chunk text as it was indexed — the exact string the embedding was computed from. */
+    text: string;
+    metadata?: Record<string, unknown>;
+}
+/** Paging for {@link VectorStore.listChunks}. Omit both to read the whole document. */
+interface ListChunksOptions {
+    /** Max chunks to return, applied after ordering by {@link StoredChunk.index}. */
+    limit?: number;
+    /** Chunks to skip, applied after ordering. */
+    offset?: number;
+}
+/** Chunk `n` of `${documentId}#<n>`; a bare document id (single-chunk document) is `0`. */
+declare function chunkIndexOf(chunkId: string): number;
 /** Collapse a chunk id (`${documentId}#<n>`) back to its source document id. */
 declare function documentIdOf(chunkId: string): string;
 
@@ -271,6 +341,16 @@ declare class MemoryVectorStore implements VectorStore {
      */
     updateMetadata(documentId: string, patch: MetadataPatch): Promise<number>;
     listDocuments(filter?: Record<string, unknown>): Promise<IndexedDocument[]>;
+    /**
+     * The chunks of one document, in document order. See {@link VectorStore.listChunks}.
+     *
+     * Insertion order is not document order — `upsert` stores whatever the caller passed, and a
+     * re-ingest that rewrites chunk 3 alone moves it to the end of the Map. So this sorts by the index
+     * parsed from the id, the same thing the SQL and Redis adapters order by, rather than trusting the
+     * Map. A reference adapter that returned "usually ordered" would let a consumer ship a bug that
+     * only shows up on the store tests are NOT written against.
+     */
+    listChunks(documentId: string, options?: ListChunksOptions): Promise<StoredChunk[]>;
     listDocumentIds(filter?: Record<string, unknown>): Promise<string[]>;
     removeMany(documentIds: string[]): Promise<void>;
     /**
@@ -349,6 +429,19 @@ declare class PgVectorStore implements VectorStore {
      */
     updateMetadata(documentId: string, patch: MetadataPatch): Promise<number>;
     listDocuments(filter?: Record<string, unknown>): Promise<IndexedDocument[]>;
+    /**
+     * The chunks of one document, in document order. See {@link VectorStore.listChunks}.
+     *
+     * The order is computed from the id rather than stored: `#12` must sort after `#2`, which a plain
+     * `ORDER BY id` gets wrong on every document past ten chunks because it compares text. So the
+     * trailing number is extracted and cast to `int`, and a bare id (a single-chunk document, which
+     * carries no `#n` suffix) collapses to `0` — the same rule `chunkIndexOf` applies in the other two
+     * adapters.
+     *
+     * `embedding` is left out of the projection: it is the widest column in the table and useless to a
+     * caller reading text back.
+     */
+    listChunks(documentId: string, options?: ListChunksOptions): Promise<StoredChunk[]>;
     /** {@link listDocuments} without the metadata: one `DISTINCT` over the derived document id. */
     listDocumentIds(filter?: Record<string, unknown>): Promise<string[]>;
     /** N documents in one statement — the set-based form of {@link PgVectorStore.remove}. */
@@ -525,6 +618,25 @@ declare class RedisVectorStore implements LexicalVectorStore {
      * document owns. The glob is escaped so `gone` does not reach into `goner#0`.
      */
     private chunkKeys;
+    /**
+     * The chunks of one document, in document order. See {@link VectorStore.listChunks}.
+     *
+     * Reads the hashes directly (`HMGET text metadata_json`) rather than going through `FT.SEARCH`.
+     * Two reasons, and the second is the one that matters: the query language has no way to ask for
+     * "every chunk of this document" — `id` is the key name, not an indexed field — and `FT.SEARCH`
+     * caps at `LIMIT`, so paging a document through it would mean ordering by a field the index does
+     * not hold. `chunkKeys` is the same enumeration {@link RedisVectorStore.remove} and
+     * {@link RedisVectorStore.updateMetadata} already use, so "the chunks this returns" and "the chunks
+     * a delete would take" cannot drift apart.
+     *
+     * It inherits that method's cost too: one keyspace `SCAN` per call. Acceptable here because this
+     * is an inspection path (one document, on demand) and not something retrieval runs — but it is why
+     * this must not be put on a hot path or called in a loop over a corpus.
+     *
+     * `embedding` is deliberately not fetched: it is by far the largest field on the hash and nothing
+     * a caller reading text back can do with it.
+     */
+    listChunks(documentId: string, options?: ListChunksOptions): Promise<StoredChunk[]>;
     listDocuments(filter?: Record<string, unknown>): Promise<IndexedDocument[]>;
     /**
      * The id-only half of {@link RedisVectorStore.listDocuments}, served by `FT.SEARCH … NOCONTENT`:
@@ -843,4 +955,4 @@ interface RetrievalTool {
  */
 declare function createRetrievalTool(retriever: Retriever, options?: RetrievalToolOptions): RetrievalTool;
 
-export { type ChunkOptions, type ChunkRecord, EmbeddingRetriever, type EmbeddingRetrieverOptions, FilteredRetriever, HybridRetriever, type HybridRetrieverOptions, type IndexedDocument, type IngestChunksOptions, type IngestDocument, type IngestOptions, KeywordRetriever, type KeywordRetrieverOptions, LexicalRetriever, type LexicalVectorStore, MemoryVectorStore, type MetadataPatch, type PgClient, PgVectorStore, type PgVectorStoreOptions, type RedisSearchClient, RedisVectorSchemaMismatchError, RedisVectorStore, type RedisVectorStoreOptions, RerankingRetriever, type RerankingRetrieverOptions, type RetrievalTool, type RetrievalToolOptions, UnsafeRemovalError, type VectorRecord, type VectorSearchOptions, type VectorStore, applyMetadataPatch, chunkDocuments, chunkText, createRetrievalTool, documentIdOf, ingestChunks, ingestDocuments, isLexicalVectorStore };
+export { type ChunkOptions, type ChunkRecord, EmbeddingRetriever, type EmbeddingRetrieverOptions, FilteredRetriever, HybridRetriever, type HybridRetrieverOptions, type IndexedDocument, type IngestChunksOptions, type IngestDocument, type IngestOptions, KeywordRetriever, type KeywordRetrieverOptions, LexicalRetriever, type LexicalVectorStore, type ListChunksOptions, MemoryVectorStore, type MetadataPatch, type PgClient, PgVectorStore, type PgVectorStoreOptions, type RedisSearchClient, RedisVectorSchemaMismatchError, RedisVectorStore, type RedisVectorStoreOptions, RerankingRetriever, type RerankingRetrieverOptions, type RetrievalTool, type RetrievalToolOptions, type StoredChunk, UnsafeRemovalError, type VectorRecord, type VectorSearchOptions, type VectorStore, applyMetadataPatch, chunkDocuments, chunkIndexOf, chunkText, createRetrievalTool, documentIdOf, ingestChunks, ingestDocuments, isLexicalVectorStore };

package/dist/index.js

@@ -9,6 +9,9 @@ function chunkText(text, options = {}) {
   if (normalized.length === 0) {
     return [];
   }
+  if (options.separator !== void 0 && options.separator.length > 0) {
+    return chunkByRecord(normalized, chunkSize, options.separator);
+  }
   if (normalized.length <= chunkSize) {
     return [
       normalized
@@ -38,6 +41,40 @@ function chunkText(text, options = {}) {
   return chunks;
 }
 __name(chunkText, "chunkText");
+function chunkByRecord(text, chunkSize, separator) {
+  const chunks = [];
+  let current = "";
+  const flush = /* @__PURE__ */ __name(() => {
+    if (current.length > 0) {
+      chunks.push(current);
+      current = "";
+    }
+  }, "flush");
+  for (const record of text.split(separator)) {
+    const trimmed = record.trim();
+    if (trimmed.length === 0) {
+      continue;
+    }
+    if (trimmed.length > chunkSize) {
+      flush();
+      chunks.push(...chunkText(trimmed, {
+        chunkSize,
+        overlap: 0
+      }));
+      continue;
+    }
+    const candidate = current.length > 0 ? `${current}${separator}${trimmed}` : trimmed;
+    if (candidate.length > chunkSize) {
+      flush();
+      current = trimmed;
+    } else {
+      current = candidate;
+    }
+  }
+  flush();
+  return chunks;
+}
+__name(chunkByRecord, "chunkByRecord");
 
 // src/vector-store.ts
 function isLexicalVectorStore(store) {
@@ -54,6 +91,11 @@ var UnsafeRemovalError = class extends Error {
     this.name = "UnsafeRemovalError";
   }
 };
+function chunkIndexOf(chunkId) {
+  const match = /#(\d+)$/.exec(chunkId);
+  return match?.[1] === void 0 ? 0 : Number(match[1]);
+}
+__name(chunkIndexOf, "chunkIndexOf");
 function documentIdOf(chunkId) {
   return chunkId.replace(/#\d+$/, "");
 }
@@ -178,6 +220,34 @@ var MemoryVectorStore = class {
       ...documents.values()
     ];
   }
+  /**
+  * The chunks of one document, in document order. See {@link VectorStore.listChunks}.
+  *
+  * Insertion order is not document order — `upsert` stores whatever the caller passed, and a
+  * re-ingest that rewrites chunk 3 alone moves it to the end of the Map. So this sorts by the index
+  * parsed from the id, the same thing the SQL and Redis adapters order by, rather than trusting the
+  * Map. A reference adapter that returned "usually ordered" would let a consumer ship a bug that
+  * only shows up on the store tests are NOT written against.
+  */
+  async listChunks(documentId, options) {
+    const chunks = [];
+    for (const record of this.records.values()) {
+      if (documentIdOf(record.id) !== documentId) {
+        continue;
+      }
+      chunks.push({
+        id: record.id,
+        index: chunkIndexOf(record.id),
+        text: record.text,
+        ...record.metadata !== void 0 ? {
+          metadata: record.metadata
+        } : {}
+      });
+    }
+    chunks.sort((a, b) => a.index - b.index);
+    const offset = options?.offset ?? 0;
+    return options?.limit === void 0 ? chunks.slice(offset) : chunks.slice(offset, offset + options.limit);
+  }
   async listDocumentIds(filter) {
     if (filterMatchesNothing(filter)) {
       return [];
@@ -364,6 +434,44 @@ var PgVectorStore = class {
       } : {}
     }));
   }
+  /**
+  * The chunks of one document, in document order. See {@link VectorStore.listChunks}.
+  *
+  * The order is computed from the id rather than stored: `#12` must sort after `#2`, which a plain
+  * `ORDER BY id` gets wrong on every document past ten chunks because it compares text. So the
+  * trailing number is extracted and cast to `int`, and a bare id (a single-chunk document, which
+  * carries no `#n` suffix) collapses to `0` — the same rule `chunkIndexOf` applies in the other two
+  * adapters.
+  *
+  * `embedding` is left out of the projection: it is the widest column in the table and useless to a
+  * caller reading text back.
+  */
+  async listChunks(documentId, options) {
+    const params = [
+      documentId
+    ];
+    let sql = `SELECT id, ${CHUNK_INDEX_FROM_ID} AS chunk_index, text, metadata
+       FROM ${this.table}
+       WHERE ${DOCUMENT_ID_FROM_CHUNK} = $1
+       ORDER BY chunk_index`;
+    if (options?.limit !== void 0) {
+      params.push(options.limit);
+      sql += ` LIMIT $${params.length}`;
+    }
+    if (options?.offset !== void 0) {
+      params.push(options.offset);
+      sql += ` OFFSET $${params.length}`;
+    }
+    const rows = await this.client.query(sql, params);
+    return rows.map((row) => ({
+      id: row.id,
+      index: Number(row.chunk_index),
+      text: row.text,
+      ...row.metadata !== null ? {
+        metadata: row.metadata
+      } : {}
+    }));
+  }
   /** {@link listDocuments} without the metadata: one `DISTINCT` over the derived document id. */
   async listDocumentIds(filter) {
     if (filterMatchesNothing(filter)) {
@@ -474,6 +582,7 @@ function buildWhere(filter, startIndex) {
 }
 __name(buildWhere, "buildWhere");
 var DOCUMENT_ID_FROM_CHUNK = "regexp_replace(id, '#[0-9]+$', '')";
+var CHUNK_INDEX_FROM_ID = "COALESCE((substring(id from '#([0-9]+)$'))::int, 0)";
 function toVectorLiteral(embedding) {
   return `[${embedding.join(",")}]`;
 }
@@ -766,6 +875,58 @@ var RedisVectorStore = class {
       ...keys
     ];
   }
+  /**
+  * The chunks of one document, in document order. See {@link VectorStore.listChunks}.
+  *
+  * Reads the hashes directly (`HMGET text metadata_json`) rather than going through `FT.SEARCH`.
+  * Two reasons, and the second is the one that matters: the query language has no way to ask for
+  * "every chunk of this document" — `id` is the key name, not an indexed field — and `FT.SEARCH`
+  * caps at `LIMIT`, so paging a document through it would mean ordering by a field the index does
+  * not hold. `chunkKeys` is the same enumeration {@link RedisVectorStore.remove} and
+  * {@link RedisVectorStore.updateMetadata} already use, so "the chunks this returns" and "the chunks
+  * a delete would take" cannot drift apart.
+  *
+  * It inherits that method's cost too: one keyspace `SCAN` per call. Acceptable here because this
+  * is an inspection path (one document, on demand) and not something retrieval runs — but it is why
+  * this must not be put on a hot path or called in a loop over a corpus.
+  *
+  * `embedding` is deliberately not fetched: it is by far the largest field on the hash and nothing
+  * a caller reading text back can do with it.
+  */
+  async listChunks(documentId, options) {
+    const keys = await this.chunkKeys(documentId);
+    const ordered = keys.map((key) => ({
+      key,
+      id: key.slice(this.prefix.length)
+    })).map((entry) => ({
+      ...entry,
+      index: chunkIndexOf(entry.id)
+    })).sort((a, b) => a.index - b.index);
+    const offset = options?.offset ?? 0;
+    const page = options?.limit === void 0 ? ordered.slice(offset) : ordered.slice(offset, offset + options.limit);
+    const chunks = [];
+    for (const entry of page) {
+      const reply = await this.client.sendCommand([
+        "HMGET",
+        entry.key,
+        "text",
+        "metadata_json"
+      ]);
+      const fields = Array.isArray(reply) ? reply : [];
+      const text = fields[0] === null || fields[0] === void 0 ? void 0 : toStr(fields[0]);
+      if (text === void 0) {
+        continue;
+      }
+      const raw = fields[1] === null || fields[1] === void 0 ? void 0 : toStr(fields[1]);
+      chunks.push({
+        id: entry.id,
+        index: entry.index,
+        text,
+        ...parseMetadata(raw)
+      });
+    }
+    return chunks;
+  }
   async listDocuments(filter) {
     if (filterMatchesNothing(filter)) {
       return [];
@@ -1655,6 +1816,7 @@ export {
   UnsafeRemovalError,
   applyMetadataPatch,
   chunkDocuments,
+  chunkIndexOf,
   chunkText,
   createRetrievalTool,
   documentIdOf,