fix(knowledge-ragflow): read source.adapterConfig.datasetId, the declared key

`extractRagflowOptions` cast the source to a shape carrying `options` and
read `options.datasetId`. `KnowledgeSourceSchema` declares `adapterConfig`
and is a plain `z.object`, so any path that parses a source drops
`options` entirely — the adapter worked only because no path parses. The
cast is removed, the adapter reads the declared key, and the refusal
names `adapterConfig.datasetId` so a host on the old spelling is told
what to write. The published README example moves with it.

Ruled: batch #160 item 2, letter A (maintainer 2026-09-18).

Claude-Session: https://claude.ai/code/session_01AhQASwqJr2Z7XfGWUdvnbF
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

packages/plugins/knowledge-ragflow/README.md

@@ -25,7 +25,7 @@ kernel.use(new KnowledgeServicePlugin({
     label: 'Product documentation',
     adapter: 'ragflow',
     source: { kind: 'http', urls: ['https://docs.example.com/sitemap.xml'] },
-    options: { datasetId: 'rgf_doc_dataset_id' }, // RAGFlow dataset to bind
+    adapterConfig: { datasetId: 'rgf_doc_dataset_id' }, // RAGFlow dataset to bind
   }],
 }));
 kernel.use(new KnowledgeRagflowPlugin({
@@ -36,7 +36,7 @@ kernel.use(new KnowledgeRagflowPlugin({
 
 ## Source binding
 
-Each `KnowledgeSource` must include `options.datasetId` pointing to a pre-created RAGFlow dataset. The adapter doesn't create datasets — operators do that once in the RAGFlow UI, where they pick the chunking method, embedding model, and rerank policy.
+Each `KnowledgeSource` must include `adapterConfig.datasetId` pointing to a pre-created RAGFlow dataset. `adapterConfig` is the key `KnowledgeSourceSchema` declares for adapter-specific configuration; a source that spells it anything else loses it on any parsing path, and the adapter refuses it by name. The adapter doesn't create datasets — operators do that once in the RAGFlow UI, where they pick the chunking method, embedding model, and rerank policy.
 
 ## What the adapter does
 

packages/plugins/knowledge-ragflow/src/__tests__/ragflow-adapter.test.ts

@@ -9,7 +9,7 @@ const source: KnowledgeSource = {
   label: 'Docs',
   adapter: 'ragflow',
   source: { kind: 'http', urls: ['https://docs.example.com'] } as KnowledgeSource['source'],
-  options: { datasetId: 'ds_42' },
+  adapterConfig: { datasetId: 'ds_42' },
 };
 
 function fakeFetch(handler: (url: string, init?: any) => unknown): { fetch: FetchLike; calls: Array<{ url: string; init: any }> } {
@@ -30,11 +30,30 @@ function fakeFetch(handler: (url: string, init?: any) => unknown): { fetch: Fetc
 }
 
 describe('KnowledgeRagflowAdapter', () => {
-  it('rejects sources without datasetId', async () => {
+  it('rejects sources without datasetId, naming the declared key', async () => {
     const { fetch } = fakeFetch(() => ({}));
     const a = new KnowledgeRagflowAdapter({ endpoint: 'http://x', apiKey: 'k', fetch });
-    const bad: KnowledgeSource = { ...source, options: {} as Record<string, unknown> };
-    await expect(a.search('q', { source: bad, topK: 1 })).rejects.toThrow(/datasetId/);
+    const bad: KnowledgeSource = { ...source, adapterConfig: {} };
+    // The refusal text is the migration notice a host reads, so it is pinned:
+    // it must name `adapterConfig.datasetId`, the key the schema declares.
+    await expect(a.search('q', { source: bad, topK: 1 })).rejects.toThrow(
+      /source\.adapterConfig\.datasetId/,
+    );
+  });
+
+  it('does not read the undeclared `options` spelling', async () => {
+    // `KnowledgeSourceSchema` is a plain `z.object`: it declares `adapterConfig`
+    // and drops `options` on any parsing path. The adapter reads the declared
+    // key only — no lenient fallback (Prime Directive #12). A host still on the
+    // old spelling is refused loudly rather than served with silence.
+    const { fetch, calls } = fakeFetch(() => ({}));
+    const a = new KnowledgeRagflowAdapter({ endpoint: 'http://x', apiKey: 'k', fetch });
+    const { adapterConfig: _dropped, ...rest } = source;
+    const legacy = { ...rest, options: { datasetId: 'ds_42' } } as unknown as KnowledgeSource;
+    await expect(a.search('q', { source: legacy, topK: 1 })).rejects.toThrow(
+      /source\.adapterConfig\.datasetId/,
+    );
+    expect(calls).toHaveLength(0);
   });
 
   it('upsert deletes-then-creates chunks and stamps objectstack metadata', async () => {
@@ -106,7 +125,7 @@ describe('KnowledgeRagflowAdapter', () => {
     const a = new KnowledgeRagflowAdapter({ endpoint: 'http://r', apiKey: 'k', fetch });
     const s: KnowledgeSource = {
       ...source,
-      options: { datasetId: 'ds_42', rerankModel: 'bge-reranker', similarityThreshold: 0.6 },
+      adapterConfig: { datasetId: 'ds_42', rerankModel: 'bge-reranker', similarityThreshold: 0.6 },
     };
     await a.search('q', { source: s, topK: 3, filter: { tag: 'a' } });
     const body = JSON.parse(calls[0].init.body);

packages/plugins/knowledge-ragflow/src/index.ts

@@ -57,23 +57,29 @@ interface RagflowSourceOptions {
   vectorSimilarityWeight?: number;
 }
 
+/**
+ * Reads this source's RAGFlow binding from `adapterConfig` — the key
+ * `KnowledgeSourceSchema` declares for adapter-specific configuration.
+ * That schema is a plain `z.object`, so any parsing path drops keys it
+ * does not declare; the adapter therefore reads the declared key and no
+ * other spelling (Prime Directive #12 — no lenient consumer).
+ */
 function extractRagflowOptions(source: KnowledgeSource): RagflowSourceOptions {
-  const opts = ((source as unknown as { options?: Record<string, unknown> }).options ?? {}) as
-    Record<string, unknown>;
-  const datasetId = opts.datasetId;
+  const cfg = source.adapterConfig ?? {};
+  const datasetId = cfg.datasetId;
   if (typeof datasetId !== 'string' || !datasetId) {
     throw new Error(
-      `RAGFlow adapter requires source.options.datasetId on source '${source.id}'`,
+      `RAGFlow adapter requires source.adapterConfig.datasetId on source '${source.id}'`,
     );
   }
   return {
     datasetId,
-    rerankModel: typeof opts.rerankModel === 'string' ? opts.rerankModel : undefined,
+    rerankModel: typeof cfg.rerankModel === 'string' ? cfg.rerankModel : undefined,
     similarityThreshold:
-      typeof opts.similarityThreshold === 'number' ? opts.similarityThreshold : undefined,
+      typeof cfg.similarityThreshold === 'number' ? cfg.similarityThreshold : undefined,
     vectorSimilarityWeight:
-      typeof opts.vectorSimilarityWeight === 'number'
-        ? opts.vectorSimilarityWeight
+      typeof cfg.vectorSimilarityWeight === 'number'
+        ? cfg.vectorSimilarityWeight
         : undefined,
   };
 }