@absolutejs/rag 0.6.0 → 0.6.2

package/dist/src/retrieval/corpus.d.ts

@@ -46,8 +46,20 @@ export declare const corpusTextHash: (text: string) => Promise<string>;
  */
 export declare const planRAGCorpus: <Owner = string>(store: RAGCorpusStore<Owner>, owner: Owner, desired: RAGCorpusDocument[]) => Promise<RAGCorpusPlan>;
 export type RAGCorpusApply<Owner = string> = {
-    /** Embed + upsert these chunks. Returns how many were written. */
-    embed: (docs: RAGCorpusDocument[], owner: Owner) => Promise<number> | number;
+    /**
+     * Embed + upsert these chunks.
+     *
+     * Return a COUNT only when the whole plan was written — the count is then
+     * taken at its word and every planned chunk is recorded as embedded. If the
+     * pass can stop early (a budget ceiling, an abort signal, a partial failure
+     * it chooses to swallow), return the chunk ids actually written instead.
+     *
+     * Getting this wrong is silent and permanent: a chunk recorded as embedded
+     * that was not will match `unchanged` on every later pass, so it is never
+     * embedded again until its source text happens to change. Reporting ids is
+     * always safe; reporting a count is a promise the caller cannot verify.
+     */
+    embed: (docs: RAGCorpusDocument[], owner: Owner) => Promise<number | readonly string[]> | number | readonly string[];
     /** Delete these chunk ids from the vector store. */
     remove: (chunkIds: string[], owner: Owner) => Promise<void> | void;
 };
@@ -56,14 +68,4 @@ export type RAGCorpusResult = {
     removed: number;
     unchanged: number;
 };
-/**
- * Bring an owner's embedded corpus in line with what they should have.
- *
- * Ordering is deliberate. Deletions run FIRST and their records are forgotten
- * only after the vectors are gone: a crash mid-pass then leaves a record whose
- * vector may already be deleted, which a later pass simply deletes again
- * (harmless), rather than a vector whose record is gone — which nothing could
- * ever find. Embedding records its digests after the write for the same reason,
- * so an interrupted run never claims to have embedded something it did not.
- */
 export declare const reconcileRAGCorpus: <Owner = string>(store: RAGCorpusStore<Owner>, owner: Owner, desired: RAGCorpusDocument[], apply: RAGCorpusApply<Owner>) => Promise<RAGCorpusResult>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@absolutejs/rag",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "homepage": "https://github.com/absolutejs/rag",
   "bugs": {
     "url": "https://github.com/absolutejs/rag/issues"
@@ -236,4 +236,4 @@
       ]
     }
   }
-}
+}