@sanqianx/project-knowledge 4.6.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        https://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       https://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,5 @@
+project-knowledge
+Copyright 2026 SanQianX
+
+This product includes software developed by SanQianX and distributed under
+the Apache License, Version 2.0.

package/README.md

@@ -0,0 +1,266 @@
+<p align="center">
+  <img src="docs/assets/logo.svg" alt="project-knowledge" width="540">
+</p>
+
+<p align="center">
+  <strong>Local, Git-triggered knowledge for software projects.</strong><br>
+  Markdown is the source of truth; the local vector index is always derived and rebuildable.
+</p>
+
+## Install
+
+### npm
+
+Complete new-machine setup is two commands:
+
+```bash
+npm install -g project-knowledge
+project-knowledge-integrations install
+project-knowledge
+```
+
+1. `npm install -g project-knowledge` installs the knowledge base CLI and its
+   bundled `ai-coding-event-bridge` dependency — nothing else to install.
+2. `project-knowledge-integrations install` is the one-time Integration Setup.
+   For every detected client (Claude Code / Codex / OpenCode) it installs two
+   independent capabilities, reported separately:
+   - **Knowledge Integration** — plugin / MCP / Skill so agents can query the
+     knowledge base;
+   - **Development Capture** — managed Bridge hooks / notify / plugin so the
+     agent conversations in real Git workspaces are captured into each
+     imported project's Development Conversation.
+   It also registers the host-level `project-knowledge` Bridge consumer.
+   No client UI needs to be opened; third-party hooks and configs are
+   preserved, and a Codex notify conflict is reported instead of overwritten.
+3. `project-knowledge` starts the local backend. Projects imported with older
+   versions are upgraded automatically on the first drain (canonical workspace
+   identity + conversation baseline — no manual migration).
+
+Notes:
+
+- Restart already-running Claude Code sessions once after installing
+  Development Capture — hooks load at session start. Only conversations after
+  setup are captured; history is never backfilled.
+- To narrow the setup: `--ide claude`, `--capture-only`, `--knowledge-only`;
+  to remove capture per client: `uninstall --capture-only`; to disable
+  capture globally (including the Bridge consumer): `disable-capture`.
+
+The local service listens on `127.0.0.1:5757` by default. The CLI can select a
+nearby free port and records the active loopback endpoint so managed Git Hooks
+do not depend on a hard-coded port.
+
+```bash
+project-knowledge              # start in the background and open the UI
+project-knowledge --fg         # run in the foreground
+project-knowledge status       # show the active local backend
+project-knowledge stop         # stop the background backend
+project-knowledge --port 9000
+project-knowledge --no-open
+```
+
+Requires Node.js 18 or newer and Git on `PATH`.
+
+### Windows desktop
+
+Install `Project-Knowledge-<version>-Setup.exe` from a project release. The
+desktop app and npm CLI use the same data directory and endpoint-ownership
+record, so only one backend owns a data directory at a time. Git and Claude
+Code are not bundled.
+
+## Runtime model
+
+There are exactly two public analysis triggers:
+
+```text
+post-commit Hook ----+
+                     +--> reconcileProjectCommits(projectId, trigger)
+application startup -+      trigger: git-hook | startup
+```
+
+Import establishes a Git tracking baseline, installs and verifies the managed
+Hook, and creates project metadata. It does not run AI, infer requirements from
+the repository, or generate placeholder knowledge. For an empty repository,
+the first later Commit is eligible for analysis.
+
+The Hook only sends a small `hook-event/v2` notification to the local backend.
+It always exits successfully when the backend is unavailable; startup then
+discovers reachable pending Commits from Git history. There is no offline task
+spool and no manual Hook or manual analysis API.
+
+Within a project, Commits run oldest-first and stop at the first failure.
+Different projects may reconcile concurrently. Hook/startup overlap for the
+same project shares one in-flight reconciliation.
+
+## Knowledge safety
+
+AI receives a frozen claim containing the Commit SHA, real patch evidence,
+bound requirement IDs, prompt hash, and fixed knowledge path. It can write only
+to an internal per-run staging directory. A manifest must validate before any
+file reaches the final project knowledge directory.
+
+Promotion uses verified hashes, backups, and a durable journal. Only after
+Markdown promotion succeeds does the analyzed-Commit pointer advance and mark
+the index dirty. Index failure never rolls back Markdown or reruns AI; it stays
+visible as dirty state and is retried.
+
+`IndexService` is the only production LanceDB writer. Incremental updates and
+full rebuilds share one process-wide FIFO. A full rebuild creates and validates
+a separate database, atomically swaps it into place, and retains the previous
+index under recovery.
+
+The application does not create, edit, refresh, or delete `CLAUDE.md`.
+
+## Requirement capture
+
+Coding-agent integrations can append the user's real request before code is
+changed. Requirement capture writes bounded metadata to the selected project's
+`requirements.jsonl`; it does not start analysis or write knowledge.
+
+The MCP server exposes:
+
+- read-only `resolve`, `search`, `ask`, `get`, and `history` tools;
+- one write-only `record_requirement` metadata tool.
+
+```bash
+npx project-knowledge@latest install
+npx project-knowledge@latest install --ide claude
+npx project-knowledge@latest install --ide codex
+npx project-knowledge@latest install --ide opencode
+```
+
+Read-only CLI examples:
+
+```bash
+project-knowledge-kb search --project <projectId> --query "refresh token policy" --json
+project-knowledge-kb ask --project <projectId> --query "what was decided about login?"
+project-knowledge-kb get --project <projectId> --entry modules/auth.md --json
+project-knowledge-kb history --project <projectId> --json
+```
+
+Queries never create or rewrite configuration. If the internal index is
+missing, dirty, or unavailable, search falls back to the project's Markdown
+and explicitly configured related projects.
+
+## Storage
+
+Default internal data directory: `~/.project-knowledge/`
+
+Override it with `KB_DATA_DIR`:
+
+```powershell
+$env:KB_DATA_DIR = 'D:\data\project-knowledge'
+project-knowledge
+```
+
+The user selects a global knowledge root before importing projects. That root
+only chooses the directory for future imports. Each imported project stores an
+absolute, fixed `knowledgePath`; changing the global root does not move existing
+projects.
+
+The selected knowledge root contains only authoritative project Markdown.
+Settings, metadata, indexes, caches, runtime state, logs, and recovery assets
+remain in the internal data directory:
+
+```text
+~/.project-knowledge/
+├── settings.json
+├── projects.json                         # minimal project ID/order index
+├── projects/<projectId>/
+│   ├── config.json                       # fixed repoPath/knowledgePath
+│   ├── state.json                        # tracking, claim, index, Hook state
+│   └── requirements.jsonl                # created only when used
+├── index/knowledge.lancedb               # one derived index
+├── cache/                                # models, exports, context packs
+├── runtime/                              # claims, staging, journals, locks
+├── logs/
+│   ├── app/
+│   ├── projects/<projectId>/
+│   └── hooks/
+└── recovery/                             # migrations, promotion/index backups
+
+<selected knowledge root>/
+└── <project storage name>/
+    ├── README.md                         # when produced by verified knowledge
+    ├── GOAL.md
+    ├── ARCHITECTURE.md
+    ├── modules/*.md
+    └── changes/*.md
+```
+
+Team knowledge is an explicit exception: an import may bind an existing
+checked-out team-store subdirectory. Its final absolute path is still fixed in
+the project config, must remain inside the selected store, and is treated as
+externally owned when the project registration is deleted.
+
+## Migration
+
+The versioned `layout-v2` migration discovers legacy assets without modifying
+them, creates a journal and centralized recovery backup, stages settings and
+per-project metadata, validates preserved paths/secrets/pointers and any legacy
+index, then activates files with the minimal registry last. The completion
+marker is written only after the new stores reopen successfully.
+
+Interrupted or failed migration keeps the legacy reader path available and
+leaves source knowledge, old logs, configuration files, and backups intact for
+retry or diagnosis.
+
+## Logging UI
+
+The production web UI is a focused structured-log console. It provides:
+
+- trace/debug/info/warn/error/fatal filtering;
+- local-date, project, component, event, operation, Commit, and text filters;
+- newest-first cursor pagination, pause/auto-refresh, and filtered export;
+- operation-flow and structured error/stack details;
+- logger health/degraded state and Hook/index/project read-only status;
+- light/dark themes and a responsive narrow-screen layout.
+
+Logs use `log/v2` JSONL, daily files and bounded segments. Retention defaults to
+365 days; `0` disables time-based deletion. Capacity cleanup is deterministic.
+Secrets are recursively redacted during write, query, error serialization, and
+export. The log root is fixed under the internal data directory.
+
+## HTTP security
+
+The default loopback server accepts same-origin/loopback browser requests. It
+does not use wildcard CORS. Binding to a non-loopback address requires
+`KB_SITE_AUTH_TOKEN`, and requests must also pass Origin validation. Public AI
+profile responses expose only masked secret metadata; generic errors return an
+operation ID without a stack. There is no raw-file route.
+
+## Repository layout
+
+```text
+_site/server.js                       # thin executable entry
+_site/lib/server-app.js               # HTTP/runtime composition
+_site/lib/storage-layout.js           # canonical internal paths
+_site/lib/project-*-store.js          # v2 registry/config/state stores
+_site/lib/project-lifecycle-service.js
+_site/lib/commit-reconciler.js
+_site/lib/knowledge-promotion.js
+_site/lib/index-service.js
+_site/lib/structured-logger.js
+_site/lib/knowledge-tool-runtime.js
+_site/scripts/hook-trigger.js
+ui/index.html                         # single production logging UI
+bin/project-knowledge*.js             # CLI and MCP entry points
+desktop/                              # Windows Electron package
+```
+
+## Testing
+
+```bash
+npm ci
+npm test -- --no-report
+npm test --prefix desktop
+npm pack --dry-run --json
+```
+
+The Windows suite includes real Git Hooks, paths with spaces/non-ASCII text,
+online and offline Commit reconciliation, crash-lock recovery, atomic index
+replacement, migration fault injection, packaged-startup contracts, API
+security, log redaction/cursors, and browser-level UI flows.
+
+## License
+
+[Apache-2.0](LICENSE). See [NOTICE](NOTICE).

package/_site/README.md

@@ -0,0 +1,30 @@
+# KB Management Site
+
+本地知识库管理界面，默认监听 `http://127.0.0.1:5757`。
+
+## 启动
+
+```bash
+node _site/server.js
+```
+
+也可以运行项目根目录的 `npm start`，或使用 `_site/start.bat`。
+
+## Commit 自动化
+
+- Git `post-commit` Hook 在应用运行时立即通知服务端。
+- 应用启动时会扫描关闭期间新增的 commit。
+- 每个 commit 生成一个独立 Claude Code 后台任务。
+- 同一项目按提交时间串行执行，不同项目可以并行。
+- 任务直接更新当前项目知识库，没有草稿审核、`autoApply` 或人工批准阶段。
+- 每个 commit 的 `discovered / queued / running / completed / failed` 状态持久化在项目 AI 工作目录中，完成的 commit 不会重复派发。
+
+## 主要接口
+
+- `GET /api/state`：项目与知识库状态。
+- `POST /api/hooks/post-commit`：接收 Hook 事件并执行 commit 对账。
+- `POST /api/projects/:slug/scan`：只读扫描 Git 状态。
+- `GET /api/projects/:slug/automation/runs`：查看自动化运行记录。
+- `GET /api/claude/sessions-stream`：订阅 Claude Code 会话状态。
+
+服务只绑定回环地址。不要将端口直接暴露到公网。

package/_site/_test/ai-profile-resolver-test.js

@@ -0,0 +1,137 @@
+// _site/_test/ai-profile-resolver-test.js
+//
+// Tests for the shared effective AI profile resolver. The resolver is the
+// single source of truth for "which AI profile does this project use right
+// now" — replacing the inconsistent fallback logic that used to live in
+// Workbench start-session / send-input, the analyzer, the CommitReconciler,
+// and import default assignment.
+//
+// Resolution order (per T01):
+//   1. projectConfig.aiProfileId when usable
+//   2. settings.ai.defaultProfileId when usable
+//   3. first usable configured profile in stable configured order
+//   4. otherwise AI_PROFILE_REQUIRED
+
+const assert = require('assert');
+const { resolveEffectiveAiProfile, isUsable, profileById } = require('../lib/ai-profile-resolver');
+
+const PROFILE_A = { id: 'profile-a', name: 'A', enabled: true, vendor: 'anthropic', model: 'm' };
+const PROFILE_B = { id: 'profile-b', name: 'B', enabled: true, vendor: 'anthropic', model: 'm' };
+const PROFILE_DISABLED = { id: 'profile-disabled', name: 'Disabled', enabled: false, vendor: 'anthropic', model: 'm' };
+const PROFILE_ENABLED_UNDEFINED = { id: 'profile-default-enabled', name: 'DefaultEnabled', vendor: 'anthropic', model: 'm' };
+
+function settings(profiles, defaultProfileId) {
+  return { ai: { schema: 'ai-profiles/v1', profiles, defaultProfileId: defaultProfileId || null } };
+}
+
+(async () => {
+  // ---- Case 1: explicit project profile is preferred ----
+  {
+    const s = settings([PROFILE_A, PROFILE_B], 'profile-b');
+    const r = resolveEffectiveAiProfile(s, { aiProfileId: 'profile-a' });
+    assert.strictEqual(r.source, 'project');
+    assert.strictEqual(r.profileId, 'profile-a');
+    assert.strictEqual(r.profile.id, 'profile-a');
+  }
+
+  // ---- Case 2: default profile fallback when project has none ----
+  {
+    const s = settings([PROFILE_A, PROFILE_B], 'profile-b');
+    const r = resolveEffectiveAiProfile(s, { aiProfileId: null });
+    assert.strictEqual(r.source, 'default');
+    assert.strictEqual(r.profileId, 'profile-b');
+  }
+
+  // ---- Case 3: first-usable fallback when default is missing/disabled ----
+  {
+    const s = settings([PROFILE_DISABLED, PROFILE_A, PROFILE_B], 'profile-disabled');
+    const r = resolveEffectiveAiProfile(s, { aiProfileId: null });
+    assert.strictEqual(r.source, 'first-usable');
+    assert.strictEqual(r.profileId, 'profile-a');
+  }
+
+  // ---- Case 4: stale project profile id falls back safely ----
+  {
+    const s = settings([PROFILE_A, PROFILE_B], 'profile-b');
+    const r = resolveEffectiveAiProfile(s, { aiProfileId: 'profile-deleted' });
+    assert.strictEqual(r.source, 'default');
+    assert.strictEqual(r.profileId, 'profile-b');
+  }
+
+  // ---- Case 5: disabled project profile falls back to default ----
+  {
+    const s = settings([PROFILE_DISABLED, PROFILE_B], 'profile-b');
+    const r = resolveEffectiveAiProfile(s, { aiProfileId: 'profile-disabled' });
+    assert.strictEqual(r.source, 'default');
+    assert.strictEqual(r.profileId, 'profile-b');
+  }
+
+  // ---- Case 6: no usable profile produces one clear error ----
+  {
+    const s = settings([PROFILE_DISABLED], null);
+    let threw = null;
+    try { resolveEffectiveAiProfile(s, { aiProfileId: null }); }
+    catch (error) { threw = error; }
+    assert(threw, 'resolver must throw when no usable profile exists');
+    assert.strictEqual(threw.code, 'AI_PROFILE_REQUIRED');
+    assert.strictEqual(threw.status, 409);
+    assert(threw.details && typeof threw.details.hint === 'string');
+  }
+
+  // ---- Case 7: enabled=undefined (legacy profiles) is treated as usable ----
+  {
+    const s = settings([PROFILE_ENABLED_UNDEFINED], 'profile-default-enabled');
+    const r = resolveEffectiveAiProfile(s, { aiProfileId: null });
+    assert.strictEqual(r.source, 'default');
+    assert.strictEqual(r.profileId, 'profile-default-enabled');
+  }
+
+  // ---- Case 8: empty settings produces AI_PROFILE_REQUIRED ----
+  {
+    let threw = null;
+    try { resolveEffectiveAiProfile({ ai: { profiles: [] } }, { aiProfileId: null }); }
+    catch (error) { threw = error; }
+    assert(threw, 'empty settings must throw AI_PROFILE_REQUIRED');
+    assert.strictEqual(threw.code, 'AI_PROFILE_REQUIRED');
+  }
+
+  // ---- Case 9: null/undefined inputs are tolerated ----
+  {
+    const r = resolveEffectiveAiProfile({ ai: { profiles: [PROFILE_A] } }, null);
+    assert.strictEqual(r.source, 'first-usable');
+    assert.strictEqual(r.profileId, 'profile-a');
+  }
+
+  // ---- Case 10: isUsable + profileById helpers ----
+  {
+    assert.strictEqual(isUsable(PROFILE_A), true);
+    assert.strictEqual(isUsable(PROFILE_DISABLED), false);
+    assert.strictEqual(isUsable(null), false);
+    const s = settings([PROFILE_A, PROFILE_B]);
+    assert.strictEqual(profileById(s, 'profile-a').id, 'profile-a');
+    assert.strictEqual(profileById(s, 'profile-unknown'), null);
+    assert.strictEqual(profileById(s, ''), null);
+  }
+
+  // ---- Case 11: deterministic first-usable order ----
+  {
+    const s = settings([PROFILE_A, PROFILE_B], null);
+    const r1 = resolveEffectiveAiProfile(s, { aiProfileId: null });
+    const r2 = resolveEffectiveAiProfile(s, { aiProfileId: null });
+    assert.strictEqual(r1.profileId, 'profile-a');
+    assert.strictEqual(r2.profileId, 'profile-a');
+  }
+
+  // ---- Case 12: default profile that is enabled=undefined still wins over first-usable ----
+  {
+    const s = settings([PROFILE_A, PROFILE_ENABLED_UNDEFINED], 'profile-default-enabled');
+    const r = resolveEffectiveAiProfile(s, { aiProfileId: null });
+    assert.strictEqual(r.source, 'default');
+    assert.strictEqual(r.profileId, 'profile-default-enabled');
+  }
+
+  console.log('ai-profile-resolver-test PASS');
+})().catch(error => {
+  console.error(error.stack || error.message);
+  process.exit(1);
+});