@sanqianx/project-knowledge 5.0.24 → 5.0.25

package/_site/_test/product-navigation-test.js

@@ -0,0 +1,152 @@
+'use strict';
+// NAV-001 — 六页导航。
+//
+// The shell owns the six-page navigation: exactly one active navigation
+// entry, exactly one visible page, and a title/hash pair that matches the
+// active view — both after a click and after the same page is restored from
+// its hash. Moving around must not write anything into the product.
+//
+// The regression drives the real product UI in a real browser against an
+// isolated instance (own port, own data dir, own knowledge dir, own Bridge
+// journal, own browser profile). Screenshots are written to
+// PK_TEST_EVIDENCE_DIR when the batch sets it, so this tracked file stays
+// free of machine-specific paths.
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const assert = require('node:assert/strict');
+
+// One temp root per run, resolved from the caller's environment: the batch
+// contract's TEMP/TMP/TMPDIR (and a CI runner's) flow into os.tmpdir(), so
+// this tracked file carries no machine-specific path and never rewrites the
+// process environment.
+const TEMP_ROOT = os.tmpdir();
+
+const { spawnServer } = require('./helpers/spawn-server');
+const { findChrome } = require('./helpers/find-chrome');
+const { launchCdpBrowser, waitFor } = require('./helpers/cdp-browser');
+const { attachNetworkCapture } = require('./helpers/cdp-network-capture');
+const freePort = require('./helpers/free-port');
+
+const ROOT = path.resolve(__dirname, '../..');
+
+const VIEWS = ['home', 'work', 'search', 'memory', 'projects', 'activity'];
+const TITLES = {
+  home: '智脑首页',
+  work: '开始工作',
+  search: '知识检索',
+  memory: '长期记忆',
+  projects: '领域与项目',
+  activity: '活动记录',
+};
+
+async function main() {
+  const fixture = fs.mkdtempSync(path.join(TEMP_ROOT, 'pk-product-navigation-'));
+  const evidenceDir = process.env.PK_TEST_EVIDENCE_DIR ? path.resolve(process.env.PK_TEST_EVIDENCE_DIR) : path.join(fixture, 'evidence');
+  fs.mkdirSync(evidenceDir, { recursive: true });
+  const port = await freePort();
+  const base = `http://127.0.0.1:${port}`;
+  const server = spawnServer({
+    root: ROOT,
+    port,
+    dataDir: path.join(fixture, 'data'),
+    tag: 'product-navigation',
+    analysisOwner: 'engine',
+  });
+  let browser;
+  try {
+    await waitFor(async () => {
+      try { return (await fetch(base + '/api/health')).ok; } catch { return false; }
+    }, 'the isolated shell', 20000);
+
+    browser = await launchCdpBrowser({
+      chrome: findChrome(),
+      profileDir: path.join(fixture, 'browser'),
+      url: base + '/',
+      width: 1920,
+      height: 1080,
+    });
+    await browser.setViewport(1920, 1080);
+    const capture = attachNetworkCapture(browser);
+    await capture.enable();
+    const run = expression => browser.evaluate(expression);
+
+    await waitFor(() => run("document.getElementById('homeContent').textContent.includes('第一个项目')"), 'the real empty home', 20000);
+    assert.equal(await run("document.querySelectorAll('nav [data-view]').length"), 6, 'the shell exposes six navigation entries');
+    assert.equal(await run("document.querySelectorAll('.view').length"), 6, 'the shell owns six pages');
+
+    const readShell = () => run(`(() => ({
+      marker: window.__navMarker === undefined ? null : String(window.__navMarker),
+      activeNav: [...document.querySelectorAll('[data-view].active')].map(button => button.dataset.view),
+      activeView: [...document.querySelectorAll('.view.active')].map(section => section.id),
+      title: (document.getElementById('pageTitle').textContent || '').trim(),
+      hash: location.hash,
+      href: location.href,
+      navCount: document.querySelectorAll('[data-view]').length,
+      documentTitle: document.title,
+      scopeActive: document.querySelectorAll('[data-scope].active').length,
+    }))()`);
+
+    const assertShell = (shell, view, phase) => {
+      const where = `${phase} (href=${shell.href}, nav=${shell.navCount}, title=${shell.documentTitle}, scopeActive=${shell.scopeActive}, exceptions=${JSON.stringify(browser.exceptions)})`;
+      assert.deepEqual(shell.activeNav, [view], `${where}: only ${view} is the active navigation entry`);
+      assert.deepEqual(shell.activeView, [`view-${view}`], `${where}: only view-${view} is the visible page`);
+      assert.equal(shell.title, TITLES[view], `${where}: the page title matches ${view}`);
+      assert.equal(shell.hash, `#${view}`, `${where}: the hash matches ${view}`);
+    };
+
+    // NAV-001 expected 1 + 2: one active entry, and title/hash/selection in
+    // agreement, after every navigation click.
+    for (const view of VIEWS) {
+      await run(`document.querySelector('[data-view="${view}"]').click()`);
+      await waitFor(() => run(`document.querySelector('[data-view="${view}"]').classList.contains('active')`), `${view} becomes the active entry`);
+      assertShell(await readShell(), view, `click ${view}`);
+      await browser.screenshot(path.join(evidenceDir, `nav-click-${view}.png`));
+    }
+
+    // The same four properties after the hash alone restores the page.
+    for (const view of VIEWS) {
+      await run(`location.hash = '#${view}'`);
+      await waitFor(() => run(`location.hash === '#${view}'`), `the ${view} hash`);
+      await run(`window.__navMarker = 'nav-${view}'`);
+      await browser.send('Page.reload');
+      // Readiness is the reloaded document itself reaching the target state:
+      // the marker disappearing proves the document really swapped, and the
+      // shell properties prove the product booted into that view - a complete
+      // readyState alone cannot show that. One atomic evaluation per attempt;
+      // two round-trips can straddle the document swap.
+      const bootedInto = view => shell => shell && shell.marker === null
+        && shell.activeNav.length === 1 && shell.activeNav[0] === view
+        && shell.activeView.length === 1 && shell.activeView[0] === `view-${view}`
+        && shell.title === TITLES[view] && shell.hash === `#${view}`;
+      await waitFor(async () => bootedInto(view)(await readShell()), `the reloaded ${view} page reaches its booted state`, 20000);
+      assertShell(await readShell(), view, `reload ${view}`);
+      await browser.screenshot(path.join(evidenceDir, `nav-reload-${view}.png`));
+    }
+
+    // NAV-001 expected 3: moving around writes nothing.
+    const writes = capture.find(entry => entry.url.includes('/api/') && !['GET', 'HEAD', 'OPTIONS'].includes(entry.method));
+    assert.deepEqual(writes.map(entry => `${entry.method} ${entry.url}`), [], 'navigation performs no business write');
+    const aggregated = await (await fetch(base + '/api/projects/aggregated')).json();
+    assert.equal(aggregated.projects.length, 0, 'navigation registers no project');
+    const brain = await (await fetch(base + '/api/brain')).json();
+    assert.equal((brain.brain.domains || []).length, 0, 'navigation creates no domain');
+    const registryPath = path.join(server.dataDir, 'projects.json');
+    if (fs.existsSync(registryPath)) {
+      const registry = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
+      assert.equal(Object.keys(registry.projects || {}).length, 0, 'the project registry stays empty');
+    }
+    const projectDirs = path.join(server.dataDir, 'projects');
+    if (fs.existsSync(projectDirs)) assert.deepEqual(fs.readdirSync(projectDirs), [], 'no project metadata directory is created');
+    assert.equal(browser.exceptions.length, 0, `no uncaught product JavaScript exceptions: ${JSON.stringify(browser.exceptions)}`);
+
+    console.log(`product-navigation-test PASS (${VIEWS.length} pages, click + hash reload, one active entry, no business write)`);
+  } finally {
+    await browser?.close();
+    await server.cleanup();
+    fs.rmSync(fixture, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+  }
+}
+
+main().catch(error => { console.error(error.stack || error.message); process.exitCode = 1; });

package/_site/_test/product-progress-status-test.js

@@ -1,84 +1,84 @@
-'use strict';
-const assert = require('node:assert/strict');
-const fs = require('node:fs');
-const os = require('node:os');
-const path = require('node:path');
-const http = require('node:http');
-const { spawnServer } = require('./helpers/spawn-server');
-const { findChrome } = require('./helpers/find-chrome');
-const { launchCdpBrowser, waitFor } = require('./helpers/cdp-browser');
-
-const ROOT = path.resolve(__dirname, '../..');
-async function main() {
-  const fixture = fs.mkdtempSync(path.join(os.tmpdir(), 'pk-product-progress-'));
-  const snapshot = { projects: [], runs: [], events: [], memories: [], sharedScopes: [] };
-  let connections = 0, snapshots = 0, healthRequests = 0;
-  const streams = new Set();
-  const upstream = http.createServer((req, res) => {
-    // The product sends the progress/snapshot reads with query parameters
-    // (e.g. /api/progress?summary=1), so route on the pathname only.
-    const cleanPath = req.url.split('?')[0];
-    if (cleanPath === '/api/progress') {
-      connections++; streams.add(res); res.on('close', () => streams.delete(res));
-      res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache' });
-      res.write(`event: snapshot\ndata: ${JSON.stringify(snapshot)}\n\n`);
-      return;
-    }
-    req.resume();
-    if (cleanPath === '/api/snapshot') snapshots++;
-    if (cleanPath.includes('/health')) healthRequests++;
-    res.writeHead(200, { 'Content-Type': 'application/json' });
-    res.end(JSON.stringify(cleanPath === '/api/snapshot' ? snapshot : cleanPath === '/api/projects' ? { projects: [] } : { ok: true, name: 'knowledge-engine', dataSchemaVersion: 3 }));
-  });
-  await new Promise(resolve => upstream.listen(0, '127.0.0.1', resolve));
-  const moduleUrl = `http://127.0.0.1:${upstream.address().port}`;
-  const port = 8400 + process.pid % 200;
-  const base = `http://127.0.0.1:${port}`;
-  const server = spawnServer({ root: ROOT, port, dataDir: path.join(fixture, 'data'), analysisOwner: 'engine', tag: 'product-progress', extraEnv: {
-    KB_TERMINAL_URL: moduleUrl, KB_VECTORHUB_URL: moduleUrl,
-    KB_EVENTBRIDGE_URL: moduleUrl, KB_KNOWLEDGE_ENGINE_URL: moduleUrl,
-  } });
-  let browser;
-  try {
-    await waitFor(async () => { try { return (await fetch(base + '/api/health')).ok; } catch { return false; } }, 'isolated product', 20000);
-    browser = await launchCdpBrowser({ chrome: findChrome(), profileDir: path.join(fixture, 'browser'), url: base, width: 1920, height: 1080 });
-    await browser.setViewport(1920, 1080);
-    const run = expression => browser.evaluate(expression);
-    const status = () => run("document.getElementById('activityConnection').textContent");
-    await waitFor(async () => await status() === '已连接实时更新', 'initial SSE snapshot');
-    assert.equal(connections, 1);
-    await run("document.querySelector('[data-view=activity]').click()");
-    await waitFor(() => run("document.getElementById('activityUpdates').textContent.includes('没有知识维护记录')"), 'genuine empty history');
-    const maintenance = journal => { snapshot.maintenance = { executionEnabled: true, consuming: true, journal }; for (const stream of streams) stream.write('event: progress\ndata: {"type":"knowledge.journal"}\n\n'); };
-    maintenance({ error: '事件消费异常', failures: [{ journalId: 'test-journal', sequence: 7, code: 'INVALID_ARGUMENT', message: '<img src=x onerror=window.__quotaXss=1>' }] });
-    await waitFor(() => run("document.getElementById('activityUpdates').textContent.includes('事件消费受阻')"), 'pre-queue failure must be visible without a run');
-    assert.equal(await run("document.getElementById('activityUpdates').textContent.includes('没有知识维护记录')"), false, 'blocked consumption cannot masquerade as an empty history');
-    assert.equal(await run("document.querySelectorAll('#activityUpdates img').length"), 0);
-    assert.equal(await run('window.__quotaXss'), undefined);
-    assert.equal(await run("document.getElementById('systemTitle').textContent"), '提交事件消费受阻');
-    maintenance({ error: null, failures: [] });
-    await waitFor(() => run("document.getElementById('activityUpdates').textContent.includes('没有知识维护记录')"), 'consumption recovery clears the warning');
-    for (let attempt = 0; attempt < 2; attempt++) {
-      const beforeHealth = healthRequests, beforeSnapshot = snapshots;
-      await run("window.dispatchEvent(new Event('online'))");
-      await waitFor(() => healthRequests > beforeHealth && snapshots > beforeSnapshot, 'online registry and snapshot refresh');
-      assert.equal(await status(), '已连接实时更新', 'a duplicate online event must not leave a healthy stream labelled as recovering');
-      assert.equal(connections, 1, 'a redundant online receipt cannot create another progress subscription');
-    }
-    await browser.send('Network.enable');
-    await browser.send('Network.emulateNetworkConditions', { offline: true, latency: 0, downloadThroughput: -1, uploadThroughput: -1 });
-    await waitFor(async () => (await status()).includes('连接中断'), 'genuine offline feedback');
-    await waitFor(() => streams.size === 0, 'offline closes the upstream stream');
-    await browser.send('Network.emulateNetworkConditions', { offline: false, latency: 0, downloadThroughput: -1, uploadThroughput: -1 });
-    await waitFor(async () => await status() === '已连接实时更新' && connections === 2, 'new snapshot and stream after real reconnection');
-    assert.equal(streams.size, 1);
-    assert.equal(browser.exceptions.length, 0);
-    console.log('product-progress-status-test PASS (real product/browser/proxy/SSE; duplicate online stays connected; real offline reconnects once)');
-  } finally {
-    await browser?.close(); await server.cleanup();
-    upstream.closeAllConnections(); await new Promise(resolve => upstream.close(resolve));
-    assert.equal(path.dirname(fixture), path.resolve(os.tmpdir())); assert.ok(path.basename(fixture).startsWith('pk-product-progress-'));
-    await fs.promises.rm(fixture, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
-  }
-}
-main().catch(error => { console.error(error.stack || error.message); process.exitCode = 1; });
+'use strict';
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const http = require('node:http');
+const { spawnServer } = require('./helpers/spawn-server');
+const { findChrome } = require('./helpers/find-chrome');
+const { launchCdpBrowser, waitFor } = require('./helpers/cdp-browser');
+
+const ROOT = path.resolve(__dirname, '../..');
+async function main() {
+  const fixture = fs.mkdtempSync(path.join(os.tmpdir(), 'pk-product-progress-'));
+  const snapshot = { projects: [], runs: [], events: [], memories: [], sharedScopes: [] };
+  let connections = 0, snapshots = 0, healthRequests = 0;
+  const streams = new Set();
+  const upstream = http.createServer((req, res) => {
+    // The product sends the progress/snapshot reads with query parameters
+    // (e.g. /api/progress?summary=1), so route on the pathname only.
+    const cleanPath = req.url.split('?')[0];
+    if (cleanPath === '/api/progress') {
+      connections++; streams.add(res); res.on('close', () => streams.delete(res));
+      res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache' });
+      res.write(`event: snapshot\ndata: ${JSON.stringify(snapshot)}\n\n`);
+      return;
+    }
+    req.resume();
+    if (cleanPath === '/api/snapshot') snapshots++;
+    if (cleanPath.includes('/health')) healthRequests++;
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(cleanPath === '/api/snapshot' ? snapshot : cleanPath === '/api/projects' ? { projects: [] } : { ok: true, name: 'knowledge-engine', dataSchemaVersion: 3 }));
+  });
+  await new Promise(resolve => upstream.listen(0, '127.0.0.1', resolve));
+  const moduleUrl = `http://127.0.0.1:${upstream.address().port}`;
+  const port = 8400 + process.pid % 200;
+  const base = `http://127.0.0.1:${port}`;
+  const server = spawnServer({ root: ROOT, port, dataDir: path.join(fixture, 'data'), analysisOwner: 'engine', tag: 'product-progress', extraEnv: {
+    KB_TERMINAL_URL: moduleUrl, KB_VECTORHUB_URL: moduleUrl,
+    KB_EVENTBRIDGE_URL: moduleUrl, KB_KNOWLEDGE_ENGINE_URL: moduleUrl,
+  } });
+  let browser;
+  try {
+    await waitFor(async () => { try { return (await fetch(base + '/api/health')).ok; } catch { return false; } }, 'isolated product', 20000);
+    browser = await launchCdpBrowser({ chrome: findChrome(), profileDir: path.join(fixture, 'browser'), url: base, width: 1920, height: 1080 });
+    await browser.setViewport(1920, 1080);
+    const run = expression => browser.evaluate(expression);
+    const status = () => run("document.getElementById('activityConnection').textContent");
+    await waitFor(async () => await status() === '已连接实时更新', 'initial SSE snapshot');
+    assert.equal(connections, 1);
+    await run("document.querySelector('[data-view=activity]').click()");
+    await waitFor(() => run("document.getElementById('activityUpdates').textContent.includes('没有知识维护记录')"), 'genuine empty history');
+    const maintenance = journal => { snapshot.maintenance = { executionEnabled: true, consuming: true, journal }; for (const stream of streams) stream.write('event: progress\ndata: {"type":"knowledge.journal"}\n\n'); };
+    maintenance({ error: '事件消费异常', failures: [{ journalId: 'test-journal', sequence: 7, code: 'INVALID_ARGUMENT', message: '<img src=x onerror=window.__quotaXss=1>' }] });
+    await waitFor(() => run("document.getElementById('activityUpdates').textContent.includes('事件消费受阻')"), 'pre-queue failure must be visible without a run');
+    assert.equal(await run("document.getElementById('activityUpdates').textContent.includes('没有知识维护记录')"), false, 'blocked consumption cannot masquerade as an empty history');
+    assert.equal(await run("document.querySelectorAll('#activityUpdates img').length"), 0);
+    assert.equal(await run('window.__quotaXss'), undefined);
+    assert.equal(await run("document.getElementById('systemTitle').textContent"), '提交事件消费受阻');
+    maintenance({ error: null, failures: [] });
+    await waitFor(() => run("document.getElementById('activityUpdates').textContent.includes('没有知识维护记录')"), 'consumption recovery clears the warning');
+    for (let attempt = 0; attempt < 2; attempt++) {
+      const beforeHealth = healthRequests, beforeSnapshot = snapshots;
+      await run("window.dispatchEvent(new Event('online'))");
+      await waitFor(() => healthRequests > beforeHealth && snapshots > beforeSnapshot, 'online registry and snapshot refresh');
+      assert.equal(await status(), '已连接实时更新', 'a duplicate online event must not leave a healthy stream labelled as recovering');
+      assert.equal(connections, 1, 'a redundant online receipt cannot create another progress subscription');
+    }
+    await browser.send('Network.enable');
+    await browser.send('Network.emulateNetworkConditions', { offline: true, latency: 0, downloadThroughput: -1, uploadThroughput: -1 });
+    await waitFor(async () => (await status()).includes('连接中断'), 'genuine offline feedback');
+    await waitFor(() => streams.size === 0, 'offline closes the upstream stream');
+    await browser.send('Network.emulateNetworkConditions', { offline: false, latency: 0, downloadThroughput: -1, uploadThroughput: -1 });
+    await waitFor(async () => await status() === '已连接实时更新' && connections === 2, 'new snapshot and stream after real reconnection');
+    assert.equal(streams.size, 1);
+    assert.equal(browser.exceptions.length, 0);
+    console.log('product-progress-status-test PASS (real product/browser/proxy/SSE; duplicate online stays connected; real offline reconnects once)');
+  } finally {
+    await browser?.close(); await server.cleanup();
+    upstream.closeAllConnections(); await new Promise(resolve => upstream.close(resolve));
+    assert.equal(path.dirname(fixture), path.resolve(os.tmpdir())); assert.ok(path.basename(fixture).startsWith('pk-product-progress-'));
+    await fs.promises.rm(fixture, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
+  }
+}
+main().catch(error => { console.error(error.stack || error.message); process.exitCode = 1; });

package/_site/_test/project-delete-recovery-test.js

@@ -1,64 +1,64 @@
-const assert = require('assert');
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-const { StorageLayout } = require('../lib/storage-layout');
-const { ProjectRegistryStore } = require('../lib/project-registry-store');
-const { ProjectStore } = require('../lib/project-store');
-const { ProjectLifecycleService } = require('../lib/project-lifecycle-service');
-
-(async () => {
-  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'pk-delete-recovery-'));
-  const layout = new StorageLayout({ dataDir: path.join(root, 'data') });
-  const registry = new ProjectRegistryStore({ layout });
-  const projects = new ProjectStore({ layout });
-  await registry.initialize();
-  const faultPoints = [
-    'delete-tombstoned',
-    'delete-before-hook', 'delete-after-hook',
-    'delete-before-registry', 'delete-after-registry',
-    'delete-before-metadata', 'delete-after-metadata',
-    'delete-before-knowledge', 'delete-after-knowledge',
-    'delete-before-completed',
-  ];
-  const hooks = {
-    uninstallHook({ projectId }) { return { ok: true, removed: true, projectId }; },
-  };
-  for (let index = 0; index < faultPoints.length; index += 1) {
-    const projectId = `project-delete-${String(index).padStart(2, '0')}`;
-    const repoPath = path.join(root, 'repos', projectId);
-    const knowledgePath = path.join(root, 'knowledge', projectId);
-    fs.mkdirSync(repoPath, { recursive: true });
-    fs.mkdirSync(knowledgePath, { recursive: true });
-    fs.writeFileSync(path.join(knowledgePath, 'README.md'), '# User knowledge\n', 'utf8');
-    await projects.create(projectId, { displayName: projectId, storageName: projectId, repoPath, knowledgePath });
-    await registry.add(projectId, { displayNameSnapshot: projectId });
-    let injected = false;
-    const failing = new ProjectLifecycleService({
-      layout, registryStore: registry, projectStore: projects, hookManager: hooks,
-      fault(point) {
-        if (!injected && point === faultPoints[index]) { injected = true; throw new Error(`fault:${point}`); }
-      },
-    });
-    await assert.rejects(
-      failing.deleteProject(projectId, { deleteKnowledge: true, confirmationToken: projectId }),
-      error => /fault:|can be retried/.test(error.message),
-      `fault ${faultPoints[index]} must stop the first attempt`,
-    );
-    assert(fs.existsSync(failing.deleteTransactionPath(projectId)), 'a durable tombstone must exist before any externally visible mutation');
-
-    const recovery = new ProjectLifecycleService({ layout, registryStore: registry, projectStore: projects, hookManager: hooks });
-    const recovered = await recovery.deleteProject(projectId, { deleteKnowledge: true, confirmationToken: projectId });
-    assert.strictEqual(recovered.ok, true, `fault ${faultPoints[index]} must recover on retry`);
-    assert(!registry.listIds().includes(projectId));
-    assert(!fs.existsSync(layout.getProjectMetadataDir(projectId)));
-    assert(!fs.existsSync(knowledgePath));
-    const journal = recovery.readDeleteJournal(projectId);
-    assert.strictEqual(journal.phase, 'completed');
-    assert(Object.values(journal.steps).every(step => step.completed), 'every delete step must be durably terminal');
-  }
-  console.log('project-delete-recovery-test PASS');
-})().catch(error => {
-  console.error(error.stack || error.message);
-  process.exitCode = 1;
-});
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { StorageLayout } = require('../lib/storage-layout');
+const { ProjectRegistryStore } = require('../lib/project-registry-store');
+const { ProjectStore } = require('../lib/project-store');
+const { ProjectLifecycleService } = require('../lib/project-lifecycle-service');
+
+(async () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'pk-delete-recovery-'));
+  const layout = new StorageLayout({ dataDir: path.join(root, 'data') });
+  const registry = new ProjectRegistryStore({ layout });
+  const projects = new ProjectStore({ layout });
+  await registry.initialize();
+  const faultPoints = [
+    'delete-tombstoned',
+    'delete-before-hook', 'delete-after-hook',
+    'delete-before-registry', 'delete-after-registry',
+    'delete-before-metadata', 'delete-after-metadata',
+    'delete-before-knowledge', 'delete-after-knowledge',
+    'delete-before-completed',
+  ];
+  const hooks = {
+    uninstallHook({ projectId }) { return { ok: true, removed: true, projectId }; },
+  };
+  for (let index = 0; index < faultPoints.length; index += 1) {
+    const projectId = `project-delete-${String(index).padStart(2, '0')}`;
+    const repoPath = path.join(root, 'repos', projectId);
+    const knowledgePath = path.join(root, 'knowledge', projectId);
+    fs.mkdirSync(repoPath, { recursive: true });
+    fs.mkdirSync(knowledgePath, { recursive: true });
+    fs.writeFileSync(path.join(knowledgePath, 'README.md'), '# User knowledge\n', 'utf8');
+    await projects.create(projectId, { displayName: projectId, storageName: projectId, repoPath, knowledgePath });
+    await registry.add(projectId, { displayNameSnapshot: projectId });
+    let injected = false;
+    const failing = new ProjectLifecycleService({
+      layout, registryStore: registry, projectStore: projects, hookManager: hooks,
+      fault(point) {
+        if (!injected && point === faultPoints[index]) { injected = true; throw new Error(`fault:${point}`); }
+      },
+    });
+    await assert.rejects(
+      failing.deleteProject(projectId, { deleteKnowledge: true, confirmationToken: projectId }),
+      error => /fault:|can be retried/.test(error.message),
+      `fault ${faultPoints[index]} must stop the first attempt`,
+    );
+    assert(fs.existsSync(failing.deleteTransactionPath(projectId)), 'a durable tombstone must exist before any externally visible mutation');
+
+    const recovery = new ProjectLifecycleService({ layout, registryStore: registry, projectStore: projects, hookManager: hooks });
+    const recovered = await recovery.deleteProject(projectId, { deleteKnowledge: true, confirmationToken: projectId });
+    assert.strictEqual(recovered.ok, true, `fault ${faultPoints[index]} must recover on retry`);
+    assert(!registry.listIds().includes(projectId));
+    assert(!fs.existsSync(layout.getProjectMetadataDir(projectId)));
+    assert(!fs.existsSync(knowledgePath));
+    const journal = recovery.readDeleteJournal(projectId);
+    assert.strictEqual(journal.phase, 'completed');
+    assert(Object.values(journal.steps).every(step => step.completed), 'every delete step must be durably terminal');
+  }
+  console.log('project-delete-recovery-test PASS');
+})().catch(error => {
+  console.error(error.stack || error.message);
+  process.exitCode = 1;
+});

package/_site/_test/project-domain-create-test.js

@@ -0,0 +1,91 @@
+'use strict';
+// PRJ-001: a domain groups knowledge; it is not a code project.
+//
+// The browser side of this case lives in product-import-ui-test.js. This file
+// covers the product contract and the disk state: an empty name is refused,
+// a named domain is persisted, and no Git project appears.
+
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnServer } = require('./helpers/spawn-server');
+const freePort = require('./helpers/free-port');
+
+const ROOT = path.resolve(__dirname, '../..');
+
+async function waitFor(fn, label, timeoutMs = 20000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try { if (await fn()) return; } catch {}
+    await new Promise(resolve => setTimeout(resolve, 100));
+  }
+  throw new Error('Timed out waiting for ' + label);
+}
+
+async function main() {
+  const fixture = fs.mkdtempSync(path.join(os.tmpdir(), 'pk-prj-domain-'));
+  const dataDir = path.join(fixture, 'data');
+  const port = await freePort();
+  const base = `http://127.0.0.1:${port}`;
+  const server = spawnServer({ root: ROOT, port, dataDir, tag: 'project-domain-create' });
+  const api = async (method, route, body) => {
+    const response = await fetch(base + route, {
+      method,
+      headers: body === undefined ? undefined : { 'Content-Type': 'application/json' },
+      body: body === undefined ? undefined : JSON.stringify(body),
+      signal: AbortSignal.timeout(10000),
+    });
+    return { status: response.status, body: await response.json() };
+  };
+  try {
+    await waitFor(async () => {
+      const response = await fetch(`${base}/api/health`, { signal: AbortSignal.timeout(2000) });
+      return response.ok;
+    }, 'isolated server');
+
+    // An empty domain name is refused by the product, not only by the form.
+    for (const name of ['', '   ', '\t\n']) {
+      const refused = await api('POST', '/api/domains', { name });
+      assert.equal(refused.status, 400, `an empty domain name must be refused: ${JSON.stringify(name)}`);
+      assert.equal(refused.body.error.code, 'INVALID_ARGUMENT');
+      assert.equal(refused.body.ok, false);
+    }
+    const tooLong = await api('POST', '/api/domains', { name: 'x'.repeat(101) });
+    assert.equal(tooLong.status, 400, 'a domain name longer than 100 characters is refused');
+
+    const created = await api('POST', '/api/domains', { name: '  研发领域  ' });
+    assert.equal(created.status, 201, JSON.stringify(created.body));
+    assert.equal(created.body.ok, true);
+    assert.equal(created.body.domain.name, '研发领域', 'the stored domain name is trimmed');
+    assert.match(created.body.domain.id, /^domain-[0-9a-f-]{36}$/);
+
+    // The domain is persisted: in the API view and in the settings file.
+    const settings = await api('GET', '/api/settings');
+    assert.ok(settings.body.settings.brain.domains.some(domain => domain.id === created.body.domain.id && domain.name === '研发领域'), 'the domain is visible in the settings view');
+    const onDisk = JSON.parse(fs.readFileSync(path.join(dataDir, 'settings.json'), 'utf8'));
+    assert.ok(onDisk.brain.domains.some(domain => domain.id === created.body.domain.id && domain.name === '研发领域'), 'the domain is persisted in settings.json');
+
+    const duplicate = await api('POST', '/api/domains', { name: '研发领域' });
+    assert.equal(duplicate.status, 409, 'a duplicate domain name is refused');
+    assert.equal(duplicate.body.error.code, 'INVALID_ARGUMENT');
+
+    // A domain never becomes a Git project.
+    const aggregated = await api('GET', '/api/projects/aggregated');
+    assert.equal(aggregated.body.projects.length, 0, 'a domain must not create a project');
+    const registryPath = path.join(dataDir, 'projects.json');
+    if (fs.existsSync(registryPath)) {
+      assert.equal(Object.keys(JSON.parse(fs.readFileSync(registryPath, 'utf8')).projects || {}).length, 0, 'the project registry stays empty');
+    }
+    const projectDir = path.join(dataDir, 'projects');
+    if (fs.existsSync(projectDir)) {
+      assert.deepEqual(fs.readdirSync(projectDir), [], 'no project metadata is written for a domain');
+    }
+    console.log('project-domain-create-test PASS (domain contract, disk persistence, no Git project)');
+  } finally {
+    await server.cleanup();
+    fs.rmSync(fixture, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+  }
+}
+
+main().catch(error => { console.error(error.stack || error.message); process.exitCode = 1; });