feat: add paged knowledge reads and verified VextJS integration

Support UTF-8 document and specification pages, streaming reads, shared snippet verification and actual cancellation. Add native VextJS provider/runtime examples, fixed-source compatibility CI and real service/browser validation entrypoints.

Reduce FileAuthority allocations and duplicate builds with source/output fingerprints. Preserve release snapshot, retrieval invalidation, capacity retirement and external temporary-directory fixes.

Author: rockyshi1993

.github/workflows/ci.yml

@@ -26,7 +26,7 @@ jobs:
           cache: npm
       - run: npm ci
       - run: npm test
-      - run: npm run test:package
+      - run: npm run test:package:built
       - run: npm ci --ignore-scripts
         working-directory: examples/seed-mcp
       - run: npm test

.github/workflows/docs-ci.yml

@@ -54,7 +54,6 @@ jobs:
             package-lock.json
             website/package-lock.json
       - run: npm ci
-      - run: npm run build
       - run: npm ci
         working-directory: website
       - run: npm run generate
@@ -88,13 +87,10 @@ jobs:
             package-lock.json
             website/package-lock.json
       - run: npm ci
-      - run: npm run build
       - run: npm ci
         working-directory: website
       - run: npm run build
         working-directory: website
-      - run: npm run check:build
-        working-directory: website
 
   docs-browser:
     runs-on: ubuntu-latest
@@ -110,9 +106,12 @@ jobs:
             package-lock.json
             website/package-lock.json
       - run: npm ci
-      - run: npm run build
       - run: npm ci
         working-directory: website
+      - uses: actions/cache@v4
+        with:
+          path: ${{ env.PLAYWRIGHT_BROWSERS_PATH }}
+          key: playwright-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
       - run: npx playwright install --with-deps chromium firefox webkit
       - run: npm run build
         working-directory: website

.github/workflows/docs-deploy.yml

@@ -45,7 +45,7 @@ jobs:
       - run: npm ci
         working-directory: website
       - run: npx playwright install --with-deps chromium
-      - run: npm run check:deployment && npm run check:types && npm run build && npm run test:site && npm run check:build && npm run check:package
+      - run: npm run check:deployment && npm run check:types && npm run build:built && npm run test:site && npm run check:package
         working-directory: website
         env:
           DEPLOYMENT_KIND: documentation

.github/workflows/release.yml

@@ -35,7 +35,7 @@ jobs:
     steps:
       - uses: actions/checkout@v7
         with:
-          ref: ${{ github.event_name == 'workflow_dispatch' && github.sha || github.ref }}
+          ref: ${{ github.event_name == 'workflow_dispatch' && format('refs/tags/{0}', github.event.inputs.release_tag) || github.ref }}
           fetch-depth: 0
           persist-credentials: false
       - id: target
@@ -73,7 +73,7 @@ jobs:
     steps:
       - uses: actions/checkout@v7
         with:
-          ref: ${{ github.event_name == 'workflow_dispatch' && github.sha || github.ref }}
+          ref: ${{ needs.freeze.outputs.release_commit }}
           persist-credentials: false
       - uses: actions/setup-node@v7
         with:
@@ -84,16 +84,16 @@ jobs:
             website/package-lock.json
       - run: npm ci
       - run: npm test
-      - run: npm run test:package
-      - run: npm run evaluate
+      - run: npm run test:package:built
+      - run: npm run evaluate:built
       - run: npm ci --ignore-scripts
         working-directory: examples/seed-mcp
       - run: npm test
         working-directory: examples/seed-mcp
       - run: npm ci
         working-directory: website
       - run: npx playwright install --with-deps chromium
-      - run: npm run check
+      - run: npm run check:built
         working-directory: website
 
   package:
@@ -108,15 +108,14 @@ jobs:
     steps:
       - uses: actions/checkout@v7
         with:
-          ref: ${{ github.event_name == 'workflow_dispatch' && github.sha || github.ref }}
+          ref: ${{ needs.freeze.outputs.release_commit }}
           persist-credentials: false
       - uses: actions/setup-node@v7
         with:
           node-version: "24"
           registry-url: "https://registry.npmjs.org"
       - run: npm install --global npm@11.15.0
       - run: npm ci
-      - run: npm run build
       - id: pack
         name: Build the immutable package artifact
         shell: bash
@@ -232,7 +231,7 @@ jobs:
     steps:
       - uses: actions/checkout@v7
         with:
-          ref: ${{ github.event_name == 'workflow_dispatch' && github.sha || github.ref }}
+          ref: ${{ needs.freeze.outputs.release_commit }}
           persist-credentials: false
       - uses: actions/setup-node@v7
         with:
@@ -254,7 +253,7 @@ jobs:
             echo "npm latest is $latest, not $PACKAGE_VERSION" >&2
             exit 1
           }
-      - run: npm run build
+      - run: npm run build:built
         working-directory: website
       - uses: actions/configure-pages@v5
       - uses: actions/upload-pages-artifact@v4
@@ -306,7 +305,7 @@ jobs:
     steps:
       - uses: actions/checkout@v7
         with:
-          ref: ${{ github.event_name == 'workflow_dispatch' && github.sha || github.ref }}
+          ref: ${{ needs.freeze.outputs.release_commit }}
           persist-credentials: false
       - uses: actions/setup-node@v7
         with:

.github/workflows/vextjs-ci.yml

@@ -0,0 +1,60 @@
+name: VextJS fixed-source compatibility
+
+on:
+  push:
+    paths: ['src/**', 'examples/**', 'scripts/**', 'test/**', 'package*.json', 'tsconfig*.json', '.github/workflows/vextjs-ci.yml']
+  pull_request:
+    paths: ['src/**', 'examples/**', 'scripts/**', 'test/**', 'package*.json', 'tsconfig*.json', '.github/workflows/vextjs-ci.yml']
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  native-and-session:
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        node: ['20.19.0', '22.12.0', '24.19.0']
+    env:
+      VEXT_SOURCE_COMMIT: ef926649926e17543562b8169982fa1786285ecf
+      VEXT_ROOT: ${{ runner.temp }}/capability-graph-vextjs-fixed
+      CG_ARTIFACTS_DIR: ${{ github.workspace }}/../capability-graph-artifacts
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@v7
+        with:
+          node-version: ${{ matrix.node }}
+          cache: npm
+      - run: npm ci
+      - run: npm run build && npm run build:tests
+      - name: Fetch and verify the fixed framework source outside the project
+        shell: bash
+        run: |
+          set -euo pipefail
+          mkdir -p "$VEXT_ROOT"
+          git -C "$VEXT_ROOT" init --quiet
+          git -C "$VEXT_ROOT" remote add origin https://github.com/devcodex-labs/vextjs.git
+          git -C "$VEXT_ROOT" fetch --depth=1 origin "$VEXT_SOURCE_COMMIT"
+          git -C "$VEXT_ROOT" checkout --detach FETCH_HEAD
+          test "$(git -C "$VEXT_ROOT" rev-parse HEAD)" = "$VEXT_SOURCE_COMMIT"
+      - name: Install the framework's lockfile and build its actual CLI
+        shell: bash
+        run: npm ci --ignore-scripts --prefix "$VEXT_ROOT" && npm --prefix "$VEXT_ROOT" run build
+      - name: Verify native catalog, retrieval and actual TCP Sessions
+        shell: bash
+        run: |
+          set -euo pipefail
+          mkdir -p "$CG_ARTIFACTS_DIR/verification"
+          node scripts/validation/vextjs-compatibility.mjs "$VEXT_ROOT" "$VEXT_SOURCE_COMMIT" > "$CG_ARTIFACTS_DIR/verification/vextjs-compatibility.json"
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: vextjs-${{ matrix.os }}-node-${{ matrix.node }}
+          path: ${{ env.CG_ARTIFACTS_DIR }}/verification/
+          retention-days: 7

README.md

@@ -150,7 +150,9 @@ npm run evaluate
 
 `npm run demo:http` 运行真实 Node.js HTTP 文档读取、能力词项召回、知识检索、过期拒绝和重建恢复，再请求业务路由。示例不调用模型；数据库与真实框架接入仍需分别实现和验证。
 
-`npm run evaluate:capacity` 执行可复用的真实文件容量验证。默认 1 万节点、2 个 Provider、10 并发，混合目录/详情/八类邻居/选择/正文/规范查询，并交错定义更新与 reload，验证关闭时已 pin 的读取完成和新查询拒绝。扩大验证可运行 `npm run evaluate:capacity -- --nodes 100000 --providers 2 --concurrency 100 --operations 3000 --duration-ms 120000 --reload-every 1000`；持续时间是负载下限，等待中的 reload/读取会延长总耗时。临时来源执行后删除，JSON 报告保留在同级产物目录。延迟和采样内存只说明本机本次运行，不是生产容量承诺。
+`npm run evaluate:capacity` 执行可复用的真实文件容量验证。默认 1 万节点、2 个 Provider、10 并发：先完整遍历全局 Catalog，核对跨 Provider 的全部身份、无遗漏和重复；再强制每个 Provider 至少两轮 reload，验证旧 previous 退出可查询槽位，同时已 pin 的查询仍能读取原视图。随后混合目录/详情/八类邻居/选择/正文/规范查询，交错定义更新与 reload，最后验证关闭时读取完成和新查询拒绝。报告分别记录 `catalogCoverage`、`retirementChecks`、负载中的 `providerQueries` 与各阶段耗时；全局 Catalog 的负载计数按页面实际出现的 Provider 统计。
+
+扩大验证可运行 `npm run evaluate:capacity -- --nodes 100000 --providers 2 --concurrency 100 --operations 3000 --duration-ms 120000 --reload-every 1000 --reload-rounds 2`。操作数至少为 `7 × Provider 数`；`--reload-rounds` 可增大但不能少于两轮，`--reload-every 0` 只关闭负载期间的交错 reload。持续时间是负载下限，完整遍历、强制 reload 及等待中的读取会增加总耗时。临时来源执行后删除，JSON 报告保留在同级产物目录。延迟和采样内存只说明本机本次运行，不是生产容量承诺。
 
 容量工具每类延迟最多保留 4096 个样本，报告标明分位数来自全量还是抽样；计数和最大值持续累计，内存统计也使用固定大小，避免验证工具自身随运行时长持续增长。
 
@@ -172,3 +174,9 @@ npm run evaluate
 ## 许可证
 
 Apache-2.0
+
+大文档使用 `readDocumentPage` / `readSpecificationPage`，模型决定范围与是否续读。默认 32 KiB 是页大小，文档总大小不设准入门槛；全文与本页哈希分开，内容变化拒绝旧游标。旧全文接口保持完整返回语义，超过单次响应容量时改用分页。
+
+VextJS 的固定原生 schema 2 接入与实际验证入口见 [examples/vextjs](examples/vextjs/README.md)。原生目录角色与来源保留，运行快照保持 partial/unknown/unverified；默认回归与外部框架、数据库、浏览器证据分开。
+
+CI 的 `test:package:built`、`evaluate:built` 和 website `build:built` 先核对源码及全部输出指纹；普通命令仍从当前源构建。共享 dist 的构建必须串行，临时报告、服务数据和浏览器输出在仓库外。

examples/seed-mcp/src/server.ts

@@ -1,5 +1,3 @@
-import { readFile } from "node:fs/promises";
-import path from "node:path";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { CapabilityGraph, CapabilityGraphError, parseQualifiedId } from "@devcodex/capability-graph";
@@ -51,6 +49,14 @@ export function createSeedServer(graph: CapabilityGraph, providerRoot: string):
     ...scope, selected: z.array(id), knowledgeIds: z.array(z.string()).optional(), roles: z.array(z.string()).optional(),
     locales: z.array(z.string()).optional(),
   } }, (query) => call(() => graph.readDocuments(query)));
+  const bodyPage = { knowledgeId: z.string(), startOffset: z.number().int().nonnegative().optional(),
+    maxBytes: z.number().int().positive().optional(), cursor: z.string().optional(), requiredStaticRevision: z.string().optional() };
+  server.registerTool("example_read_document_page", { description: "Read a document page. For large sources, decide whether to continue with nextCursor. Full-document and page hashes are separate.", inputSchema: {
+    ...bodyPage, capability: id,
+  } }, (query, extra) => call(() => graph.readDocumentPage({ ...query, signal: extra.signal })));
+  server.registerTool("example_read_specification_page", { description: "Read one Specification document page and optionally continue with its version-bound cursor.", inputSchema: {
+    ...bodyPage, providerId: z.string(),
+  } }, (query, extra) => call(() => graph.readSpecificationPage({ ...query, signal: extra.signal })));
   server.registerTool("example_read_specification", { description: "Explicitly read selected Specification documents from one Provider.", inputSchema: {
     providerId: z.string(), knowledgeIds: z.array(z.string()).optional(), locales: z.array(z.string()).optional(),
     requiredStaticRevision: z.string().optional(),
@@ -66,8 +72,11 @@ export function createSeedServer(graph: CapabilityGraph, providerRoot: string):
     ...scope, project: z.string(), environment: z.string(), instanceOf: id.optional(), instanceId: z.string().optional(),
     requiredRuntimeRevision: z.string().optional(), cursor: z.string().optional(), limit: z.number().int().positive().optional(),
   } }, (query) => call(() => graph.queryRuntime(query)));
-  server.registerResource("provider-specification", "seed://provider/specification", { mimeType: "text/markdown" }, async (uri) => ({
-    contents: [{ uri: uri.href, mimeType: "text/markdown", text: await readFile(path.join(providerRoot, "PROVIDER.md"), "utf8") }],
-  }));
+  server.registerResource("provider-specification", "seed://provider/specification", { mimeType: "text/markdown" }, async (uri) => {
+    const batch = await graph.forProvider("seed.http").readSpecification({ knowledgeIds: ["SPEC-01"] });
+    const slot = batch.results[0];
+    if (!slot || !slot.ok) throw new CapabilityGraphError(slot && !slot.ok ? slot.error.code : "CG_NOT_FOUND", { nextAction: "repair_source" });
+    return { contents: [{ uri: uri.href, mimeType: "text/markdown", text: slot.value.text }] };
+  });
   return server;
 }

examples/seed-mcp/test/server.test.ts

@@ -28,7 +28,7 @@ async function connected(run: (client: Client, graph: CapabilityGraph) => Promis
 }
 test("MCP: initialize and enumerate query tools, not one tool per capability", async () => connected(async (client) => {
   const list = await client.listTools();
-  assert.equal(list.tools.length, 12);
+  assert.equal(list.tools.length, 14);
   assert.ok(list.tools.every((tool) => tool.name.startsWith("example_")));
   assert.equal(JSON.stringify(list).includes("D-02"), false);
 }));
@@ -45,6 +45,10 @@ test("MCP: static and document queries exactly match the same Core API", async (
       await graph.readSpecification({ providerId: "seed.http", knowledgeIds: ["SPEC-01"] })],
     ["example_read_documents", { selected: [canonical("route.validation"), canonical("schema.request")] },
       await graph.readDocuments({ selected: [canonical("route.validation"), canonical("schema.request")] })],
+    ["example_read_document_page", { capability: canonical("route.validation"), knowledgeId: "D-02", maxBytes: 20 },
+      await graph.readDocumentPage({ capability: canonical("route.validation"), knowledgeId: "D-02", maxBytes: 20 })],
+    ["example_read_specification_page", { providerId: "seed.http", knowledgeId: "SPEC-01", maxBytes: 20 },
+      await graph.readSpecificationPage({ providerId: "seed.http", knowledgeId: "SPEC-01", maxBytes: 20 })],
   ];
   for (const [name, args, expected] of checks) {
     const actual = await client.callTool({ name, arguments: args });
@@ -108,7 +112,7 @@ test("MCP: actual stdio child serves requests and exits on close", async (contex
   let pid: number | null = null;
   try {
     await client.connect(transport); pid = transport.pid; assert.ok(pid);
-    assert.equal((await client.listTools()).tools.length, 12);
+    assert.equal((await client.listTools()).tools.length, 14);
     const result = payload(await client.callTool({ name: "example_list_catalog", arguments: {} }));
     assert.equal((result.items as unknown[]).length, 5);
   } finally { await client.close(); await transport.close(); }

examples/seed-runtime/README.md

@@ -8,7 +8,7 @@
 
 `knowledge-reader.ts` 限制来源 origin、并发数、总时限和原始响应字节，拒绝重定向与压缩；超时及关闭都会销毁请求并等待连接关闭。`text-retrieval.ts` 是确定性的内存词项索引，使用有限缓存，按已选 targets 重查内容身份；零命中也需要有效证据。静态定义、正文或分块配置变更后，由接入方显式重建或调用 invalidate，Core 不自动刷新。
 
-分块保留 UTF-8 BOM 和补充字符，偏移对应原始正文的字节。缓存按选择做 LRU 淘汰；即便正文和静态修订相同，切换知识根目录仍须失效旧映射。来源读取失败不会伪装成缓存成功，能力索引重建超容量也不会发布半个索引。这些边界分别由根 `test/http-retrieval.test.ts` 和 `test/text-retrieval.test.ts` 通过真实来源验收。
+分块保留 UTF-8 BOM 和补充字符，偏移对应原始正文的字节。缓存按选择做 LRU 淘汰；即便正文和静态修订相同，切换知识根目录仍须失效旧映射。每次检索固定读取预算、分块和停用词配置；invalidate 按 Provider 标记在途请求，旧请求可以完成原来的快照，但不能在失效后回填旧缓存或覆盖新缓存。无关 Provider 的失效保持隔离，查询结束时释放在途标记。来源读取失败不会伪装成缓存成功，能力索引重建超容量也不会发布半个索引。这些边界分别由根 `test/http-retrieval.test.ts` 和 `test/text-retrieval.test.ts` 通过真实来源验收。
 
 这条路径使用零次模型调用，证明本机 HTTP 和检索链路，不证明语义搜索质量或 Agent 任务成功率。临时 Provider 位于仓库同级 `capability-graph-artifacts`，结束后关闭 Reader、graph、HTTP 服务并清理自建目录。正式回归位于根 `test/http-retrieval.test.ts`。
 
@@ -35,3 +35,5 @@ node dist-test/examples/seed-runtime/main.js '{"project":"sample-app","environme
 ## 验证
 
 `test/real-runtime.test.ts` 启动独立子进程，实际请求业务路由并沿 API 完成目录、关系、实例和知识流程；随后核对项目/环境隔离、源变化、旧构建、失联/恢复及分页。进程 PID 与端口在测试诊断中输出，结束后验证进程不存在且监听端口可重新绑定。IPC 注册只供这个可控制参考应用演示动态注册，不暴露为 HTTP 管理入口。
+
+Reader 可实现 `stream`：Core 计算全文哈希，页只保留所选范围，单块大小有界。HTTP 参考支持无 Range 来源、完整转移期限和 AbortSignal 终止真实请求。TextKnowledgeRetriever 用 scan 消费大正文；configure 的 pageBytes 是页大小，maxDocumentBytes 保留为旧名称。仅提供 read 的旧宿主仍使用有界全文回退。