perceptkit 0.2.2__tar.gz

perceptkit-0.2.2/.github/workflows/release.yml

@@ -0,0 +1,136 @@
+name: release
+
+# 打 tag 时由 CI 构建并发布 wheel，同时生成构建出处凭证（provenance attestation）。
+#
+# 为什么不在本机编好再传：哈希锁只能证明「装进宿主镜像的字节 = 发布出去那份
+# 字节」，证明不了「这份字节是由公开 tag 的源码编出来的」。本机编 + 手工上传
+# 时，有仓库权限的人可以传一个跟源码对不上的 wheel，看源码的人看不出问题。
+#
+# 由 tag 触发的 CI 编译 + GitHub 签发的 attestation 把这一环补上：凭证里绑定了
+# 仓库、workflow、commit 和产物摘要，任何人都能独立验证：
+#
+#     gh attestation verify <wheel> --repo teleport-computer/perceptkit
+#
+# v0.2.0 / v0.2.1 是本机编好手工传的（当时还没有这个 workflow），所以那两个
+# 版本没有凭证 —— 从 v0.2.2 起有。
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "要重新发布的 tag（不填则用当前 ref）"
+        required: false
+
+permissions:
+  contents: write        # 建 Release、传产物
+  id-token: write        # 换取 OIDC token 用于签发凭证
+  attestations: write    # 写 attestation
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.inputs.tag || github.ref }}
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        run: pipx install uv
+
+      - name: Tag 与 pyproject 版本必须一致
+        # 不一致就停：否则会出现「tag 是 v0.2.2、wheel 却是 0.2.1」这种凭证与
+        # 产物名对不上的情况，验证方无从判断该信哪个。
+        run: |
+          TAG="${GITHUB_REF_NAME#v}"
+          PKG=$(grep -m1 '^version = ' pyproject.toml | cut -d'"' -f2)
+          echo "tag=$TAG  perceptkit=$PKG"
+          test "$TAG" = "$PKG" || { echo "::error::tag $TAG 与版本 $PKG 不一致"; exit 1; }
+
+      - name: 跑测试
+        # 发一个测试不过的包出去比不发更糟 —— 装它的人会以为它是可用的。
+        run: uv run --extra dev pytest tests/ -q
+
+      - name: 示例必须能脱离宿主跑通
+        # 这是包对外的核心承诺（不采集数据、不碰存储、不调模型，
+        # 因此也就不需要 io、不需要 API key、不需要网络）。
+        # 发版时验一次，比等使用者发现便宜得多。
+        run: |
+          uv run python examples/quickstart.py
+          uv run python examples/end_to_end.py
+
+      - name: 构建
+        run: |
+          uv build
+          mkdir -p out
+          cp dist/* out/
+
+      - name: 传产物给发布 job
+        uses: actions/upload-artifact@v4
+        with:
+          name: dists
+          path: out/
+
+      - name: 生成构建出处凭证
+        uses: actions/attest-build-provenance@v1
+        with:
+          subject-path: "out/*"
+
+      - name: 记录产物摘要
+        # 打进 job 日志，方便对照 Release 页和宿主 lock 里的哈希。
+        run: |
+          echo "### 产物摘要" >> "$GITHUB_STEP_SUMMARY"
+          echo '```' >> "$GITHUB_STEP_SUMMARY"
+          sha256sum out/* >> "$GITHUB_STEP_SUMMARY"
+          echo '```' >> "$GITHUB_STEP_SUMMARY"
+          sha256sum out/*
+
+      - name: 发布到 Release
+        # 继续发 GitHub Release，不只发 PyPI：宿主的哈希锁现在钉的是 Release
+        # 上的 wheel URL，换成 PyPI 是另一件事（要重算哈希、改 lock），
+        # 两件事分开做。两边发的是**同一批字节**。
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          TAG="${GITHUB_REF_NAME}"
+          if gh release view "$TAG" >/dev/null 2>&1; then
+            gh release upload "$TAG" out/* --clobber
+          else
+            gh release create "$TAG" out/* --title "perceptkit $TAG" --generate-notes
+          fi
+
+  # --------------------------------------------------------------------------
+  # PyPI 发布单独一个 job
+  #
+  # 仓库里不存 token，走 OIDC（Trusted Publishing）。`id-token: write` 是每个
+  # job 各自声明的 —— 顶层的 permissions 不会自动传进来。
+  #
+  # environment 名字要和 PyPI 上那条 Trusted Publisher 配置填的一致。
+  # 姊妹仓库 memgarden 因为一个仓库里发两个包、必须靠 environment 区分才不被
+  # PyPI 判为歧义；这里只有一个包，本可以不填，仍然填上是为了两个仓库的配置
+  # 长得一样，照着抄的人不会踩到那个坑。
+  publish-pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi-perceptkit
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dists
+          path: out
+      - name: 发布到 PyPI
+        # 🔴 不要加 continue-on-error。加了之后 job 会判成 success，
+        # 「发布失败」和「发布成功」在 Actions 页面上长得一模一样 ——
+        # 姊妹仓库踩过一次，结果 PyPI 上躺着一个依赖装不上的版本。
+        # 让它红是安全的：GitHub Release 在上一个 job 里已经发完了。
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: out/
+          skip-existing: true

perceptkit-0.2.2/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+*.db
+dist/

perceptkit-0.2.2/CHANGELOG.md

@@ -0,0 +1,117 @@
+# 变更记录
+
+## 0.2.2 — 未发布
+
+**代码没有变化。** 这一版只换了「怎么发出去」。
+
+### 变更
+
+- **发版改由 CI 在 tag 上构建，并带 GitHub 签发的出处凭证。**
+  0.2.0 / 0.2.1 是在本机编好、手工传上去的。宿主的哈希锁只能证明
+  「装进镜像的字节 = 发布页上那份字节」，**证不了这份字节是那个 tag 的源码
+  编出来的** —— 有仓库权限的人可以传一个跟源码对不上的 wheel，
+  而看源码的人看不出问题。现在任何人都能独立验：
+
+      gh attestation verify perceptkit-0.2.2-py3-none-any.whl \
+          --repo teleport-computer/perceptkit
+
+- **开始发 PyPI**（`pip install perceptkit`），走 Trusted Publishing，
+  仓库里不存 token。GitHub Release 照旧发**同一批字节** —— 宿主目前钉的是
+  Release 的 wheel URL，换成 PyPI 是另一件事。
+
+
+## 0.2.1 — 2026-08-31
+
+### 新增
+
+- **conformance 多了第 ⑪ 条：两个来源镜像都要能往返。**
+  这一条是从一个真实现上倒推出来的 —— 宿主的 Postgres adapter 写提醒时读了
+  `r.source_created_at`、读回来时又把它当构造参数传回去，而
+  `ReminderItemMirror` 上根本没有这个字段（`CalendarEventMirror` 有，
+  它是照那个写的）。**写会抛、读也会抛，整条提醒镜像从来没通过过一次**，
+  而这套套件全绿。
+
+  原因是 ⑧ 一直在用日历，所以日历那半始终被覆盖着，提醒那半一次都没被碰过。
+  **一个只测一半的套件，给出的是「都测过了」的印象。**
+
+
+## 0.2.0 — 2026-08-31
+
+**这一版有破坏性变更。** 宿主升级时要改 import，见下。
+
+### 破坏性
+
+- **纯计算的八个模块搬进 `perceptkit.algorithms`**
+  （`attribution` / `glance` / `history` / `identity` / `observation` /
+  `streaks` / `trend_models` / `wake`）。
+
+  ```python
+  # 之前
+  from perceptkit import trend_models
+  from perceptkit.history import ...
+
+  # 之后
+  from perceptkit.algorithms import trend_models
+  from perceptkit.algorithms.history import ...
+  ```
+
+  产品规范 §18 要求这一层单独存在（「不能再把 contract、算法、存储、
+  宿主 runtime 接线混成一层」）。先前它们和 `kit.py`（装配和接线）平级。
+
+  `catalog` / `fields` / `retention` / `prompts` **留在顶层没动** ——
+  它们是声明表和待定项，不是算法。
+
+- **`list_events` 改为返回 `(事件, 下一页游标)`**，不再是一个列表。
+  产品规范 §15 要求所有 list 查询分页或有明确上限。
+
+### 新增
+
+- `list_definitions()` —— 当前配了哪些规则（规范 §15 列了它，先前完全没有）。
+- `list_events(status=...)` —— 按投递状态筛。「为什么没提醒我」的答案
+  往往是 suppressed 或 rejected，不是 pending。
+- `export_subject()` —— 按人导出。规范 §8 要的是「定位、导出、删除」，
+  导出那一半先前是空的。
+- `recompute_aggregates()` —— 聚合算法升级后重算历史。**默认拒绝重算
+  明细可能已被保留期清理的日子**：拿残缺明细折出来的永久统计会错一个
+  数量级，而且旧值已被覆盖。
+- 重复日程按查询窗口滚动展开（确定的子集；不认识的规则明确拒绝，不猜日期）。
+- `run_wake_conformance()` / `run_report_conformance()` —— 规范 §20 并列的
+  三种 adapter conformance，先前只有 storage 那一套。
+- manifest 的第五条自动检查：投影不漂移。它抓的一类是泄漏 ——
+  声明了「永不给 agent」的字段如果 wake_eligible，前后值会随事件信封
+  存下来、投出去、进模型上下文。
+- manifest 拆出 `aggregate_retention_days`：明细和聚合是两个保留期。
+- 新增信号：`proximity_anchor` / `music_playback` / `app_usage`。
+- 事件信封的 `context` 带上触发字段的单位。
+
+### 修复
+
+- **同一个信号里两种聚合算法会互相覆盖，当天第二条上报直接崩。**
+  聚合分派把**整条 payload** 递给了每个字段的 merger，于是一个字段声明的
+  算法写到了所有字段头上。`health_vitals` 同时有 `numeric_dist`（静息心率）
+  和 `main_of_day`（vo2_max）：后者把字段写成裸数字，前者下一条进来读
+  `cell["min"]` 抛 `AttributeError` —— **每个用户每天第二次上报都会踩**。
+  同一个原因还让声明 `none` 的字段凭空长出聚合（`weather` 只声明了
+  `temperature_c`，紫外线、湿度、体感温度全被写了 min/max/sum/count）。
+  现在每个 merger 只拿到它自己那个字段。
+
+  没被单测抓到，是因为所有单测用的信号都只声明了一种算法；影子第一次接
+  真数据当天就炸了。
+
+- **`unavailable` 现在会写进当前值。** 先前撤销权限后查询仍报 `fresh` ——
+  把一个已经读不到的值当成当前事实。现在状态记下来、最后可靠值留作
+  `last_known`。
+- **设备时钟明显错误的判据**：超过 24 小时的未来时间拒收（过去不限，
+  离线补传是正常的）。先前没有任何判据，手机时间设成明年会把今天的数据
+  写进明年，不报错。
+- **事件 `context` 的白名单和长度上限真的实现了** —— 先前只写在文档里。
+- **日历/提醒的读取走端口**，不再摸具体实现的私有属性（那会让任何真实
+  存储静默返回空）。
+- **一致性套件自己不再摸内存实现的内部** —— 先前它对每个真 adapter
+  都报一个假失败。
+- 接受规范 §7.1 用的字段名 `state` / `sample_id` 作为别名。照那份文档
+  实现的 producer 先前每一条观测都被拒。
+
+## 0.1.0
+
+首个公开版本：判断内核（纯函数）。

perceptkit-0.2.2/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://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
+
+       http://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.

perceptkit-0.2.2/NOTES-packaging.md

@@ -0,0 +1,197 @@
+# perceptkit 打包笔记
+
+镜像对象：`/tmp/mg-peek`（memgarden，同一个团队更早做的一次同类抽取）。
+布局、`pyproject.toml` 写法、`__init__.py` 语气、守卫测试风格都照它来。
+
+## 1. 依赖验证
+
+`src/perceptkit/*.py` 的全部 import（AST 扫描，排除包自身）：
+
+```
+$ python3 - <<'EOF'
+import ast, pathlib, sys
+SRC = pathlib.Path("src/perceptkit")
+stdlib = set(sys.stdlib_module_names)
+...
+EOF
+all imports: ['__future__', 'collections', 'dataclasses', 'datetime', 'hashlib', 'json', 'math', 'sys', 'typing', 'zoneinfo']
+non-stdlib (excluding self): set()
+```
+
+零第三方依赖，全部标准库。`pyproject.toml` 的 `dependencies = []`。
+
+## 2. pyproject.toml
+
+照 memgarden 的写法：hatchling、`src/` 布局、`license = { file = "LICENSE" }`、
+`requires-python = ">=3.10"`、`[tool.pytest.ini_options] testpaths = ["tests"]`。
+唯一实质差异：memgarden 有一个允许的同源第三方依赖
+（`agent-protocol-core`），这个包没有等价的同源伙伴包，`dependencies = []`
+是真正的空。
+
+## 3. `src/perceptkit/__init__.py`
+
+重写成 memgarden 的语气：先说包判断什么，再列一段"不在这里的"（数据采集、
+存储、加解密、账号身份与鉴权、定时器/调度、真正调模型、决定 agent 最终该
+说什么），最后 re-export 十二个模块里宿主大概率会直接用到的名字（
+`should_wake`、`build_perception_glance`、`classify`、`measurement_key` 等，
+完整列表见 `__all__`）。
+
+## 4. 迁移测试：改动前后
+
+**改动前**（host 仓库 `/Users/hx/Projects/io/worktrees/feedling-mcp/feat-perception-health-chain/tests/`，
+10 个 `test_perception_kernel_*.py` 文件）：
+
+```
+grep -c '^    def test_\|^def test_' 逐文件相加 = 95   （parametrize 只按函数定义算一次）
+```
+
+按 pytest 实际会收集的用例数手工展开 parametrize（未在此仓库跑 pytest —— host
+仓库的 conftest 会尝试连 Postgres，用手工核对参数化列表长度代替）：
+
+```
+test_identity.py     test_missing_any_part_is_refused        1 def -> 4 cases（kwargs 列表长度 4）      +3
+test_wake.py          test_deny_listed_signals_are_never_wake_worthy  1 def -> 5 cases（NOT_WAKE_WORTHY_SIGNALS 长度 5）  +4
+test_wake.py          test_durable_wake_signals_default_allow         1 def -> 7 cases（手写信号列表长度 7）              +6
+```
+
+**改动前实际总数：95 + 3 + 4 + 6 = 108**
+
+**改动后**（`perceptkit/tests/`，`uv run python3 -m pytest --collect-only -q`）：
+
+```
+106 tests collected in 0.02s
+```
+
+差值 108 → 106 的构成：
+
+- **删除 6 条宿主集成测试**（它们断言宿主的 re-export 壳和内核对象是同一批
+  对象，或直接读/扫宿主仓库的源码——这个独立包里既没有宿主壳、也没有宿主
+  仓库目录，留着要么 ImportError 要么变成"扫空目录、永远绿"的假测试）：
+  - `test_catalog.py::test_io_shell_reexports_the_same_objects`
+  - `test_projection.py::test_io_shells_reexport_kernel_objects`
+  - `test_wake.py::test_kernel_vocabulary_does_not_collide_with_the_two_io_wake_kind_sets`
+    （硬编码了宿主另外两套 wake_kind 常量，纯粹比对宿主内部事实）
+  - `test_wake.py::test_wake_unwired_names_stay_unreferenced_outside_the_kernel`
+    （扫宿主仓库 `backend/`、`tools/` 目录；这里没有这两个目录，会静默
+    "扫空、永远绿"，是比失败更危险的假测试）
+  - `test_wake.py::test_every_real_durable_wake_signal_is_wake_worthy`
+    （直接 `read_text()` 宿主的 `perception/differ_v2.py` 源码核对信号名单，
+    这个文件不存在于本仓库）
+  - `test_purity.py`（宿主版本本身就是扫宿主 `backend/`+`tools/` 目录的，
+    不适合直接照搬——用它的思路重写了一份，见下）
+- **新增 4 条**：`test_purity.py`（3 条）+ `test_no_host_leakage.py`（1 条）
+
+`108 - 6 + 4 = 106`，与实际收集数一致。
+
+文件改名对照：`test_perception_kernel_X.py` -> `test_X.py`；`catalog`/`projection`
+两个文件里删掉了宿主集成用例后保留文件名不变（`projection` 原本就是
+`fields.py` + `glance.py` 两个模块的联合测试，没有对应单模块名可用）。
+所有文件里的手写 `sys.path` bootstrap 全部删除，`import perception_kernel.X`
+/`from perception_kernel import X` 全部改成 `import perceptkit.X` /
+`from perceptkit import X`。
+
+## 5. `tests/test_purity.py`
+
+照抄 memgarden 版本的结构（AST 扫描 `src/perceptkit` 下每个文件的顶层
+import），**唯一差异是允许名单是空集**（memgarden 允许同源的
+`agent-protocol-core`，这个包没有等价的伙伴包）。三条测试：源码树非空
+（护住扫描路径没写错）、无第三方 import、判断内核不碰网络/DB/进程/线程。
+
+## 6. `tests/test_no_host_leakage.py`
+
+选词标准：**只挑结构性的、不含糊的标识符**，不禁常见词。具体选了这些：
+
+| 词 | 为什么 |
+|---|---|
+| `perception_kernel` | 宿主迁移前的内部包名——留着就是没洗干净的直接证据 |
+| `io_cli` | 宿主内部 CLI 工具名 |
+| `chat_resident_consumer` | 宿主 VPS 自托管常驻进程的模块名 |
+| `differ_v2` / `signal_state_v2` / `effect_outbox` / `tool_executor_v2` | 宿主运行时内部模块名 |
+| `model_api_runtime` | 宿主的运行时 lane 名——这个包要兼容多条宿主 runtime，写死一条的名字就是假设了宿主架构 |
+| `OpenClaw` | 宿主生态里的第三方插件名 |
+| `backend/*.py` / `tools/chat_resident_consumer.py` | 宿主仓库的目录布局，这个包不该假设自己在哪个宿主仓库下 |
+| `perception_daily` | 宿主数据库的实际表名——这个包不碰存储，不该知道表叫什么 |
+| `usr_[0-9a-f]{8,}` | 真实用户 id 的形状（照抄 memgarden） |
+| `ADMIN_KEY` | 凭据名（照抄 memgarden） |
+
+**刻意没禁**裸的 `io`（宿主产品名）：只有两个字母，是标准库模块名
+（`import io`）的合法用法，也是大量英文缩写/变量名的子串，禁了假阳性远大于
+真阳性；用更具体的标识符（内部模块名、插件名、表名、目录）来兜底同一个
+"产品名泄漏"担忧，风险小得多。
+
+扫描范围只覆盖 `src/`、`README.md`、`pyproject.toml`，**刻意不扫
+`tests/`**——这条测试自己就活在 `tests/` 里，它的 `BANNED` 正则字面量本身
+含有这些词，扫自己会自证失败（踩过一次：第一版把 `tests/` 也扫进去，
+测试文件里解释"删掉了什么"的说明文字被自己的正则命中）。
+
+## 7. 一个意外发现：`src/perceptkit/*.py`（"已经就位"的文件）本身就在泄漏
+
+写完 leakage 测试、第一次跑之前先手动 grep 了一遍 `src/`（不是等测试跑起来
+才发现），结果是：这批已经放在 `src/perceptkit/` 里的源码**本身携带大量
+宿主内部细节**，集中在 `wake.py`、`prompts.py`、`fields.py`、`catalog.py`、
+`history.py` 五个文件的注释/docstring 里：
+
+- 宿主内部文件路径 + 行号（如 `proactive/gate.py:89`）
+- 宿主内部函数名/常量名（如 `_proactive_v2_wake_kind`、`_COLLISION_WAKE_KINDS`、
+  各种 `SWITCH_*_WAKE_ENABLED` 开关名）
+- 宿主运行时 lane 名（`model_api_runtime/v2/...`）
+- 宿主内部模块名（`differ_v2.py`、`chat_resident_consumer.py`、
+  `signal_state_v2.py`、`backend/capabilities/tool_schema.py`）
+- 宿主内部工具名（`io_cli`）与生态插件名（`OpenClaw`）
+- 宿主产品名的直接提及（`IO'S OWN foreground/background/inactive phase`）
+- 宿主数据库表名（`perception_daily`）与技术选型（Postgres）
+- 一处真人名字（"hx 拍板"，指代团队里的决策者）
+- 一处指向宿主仓库内部测试 fixture 的路径断言
+  （`tests/fixtures/perception_kernel/prompt_baseline.json`，该路径在这个
+  独立包里根本不存在，留着是死断言）
+
+这些注释本身的**设计理由是有价值的**（比如为什么 wake 源要单独起名、为什么
+默认允许+否决名单而非白名单），所以没有整段删掉，而是改写成不点名宿主内部
+结构的版本，保留"为什么这么设计"，去掉"宿主哪个文件哪一行"。逐文件改动：
+`wake.py`（改动最大）、`catalog.py`、`fields.py`、`prompts.py`、`history.py`。
+
+这不是"任务外顺手改了别的东西"——这批文件被判定为"标准做法就是照抄测试
+规范，然后让测试盯着"，而写完的 `test_no_host_leakage.py` 本该、也确实
+应该抓到这个问题；不修就没法让 `pytest` 通过，也违背了整个任务"证明这个
+包能独立发布"的前提。
+
+## 8. 运行方式
+
+用 `uv`（`/tmp/mg-peek` 的 `[tool.uv.sources]` 暗示这个团队的约定，且本机
+已装 `uv 0.11.7`）：
+
+```
+$ uv sync --extra dev
+Resolved 10 packages in 484ms
+Building perceptkit @ file:///Users/hx/Projects/perceptkit
+Installed 6 packages: iniconfig, packaging, pluggy, pygments, pytest, perceptkit
+
+$ uv run python3 -m pytest -q
+........................................................................ [ 67%]
+..................................                                       [100%]
+106 passed in 0.06s
+```
+
+也验证了不带 `uv run`、只激活 `.venv` 后跑纯 `python3 -m pytest` 同样通过
+（`uv sync` 把包装成 editable install，`perceptkit` 在 sys.path 上）：
+
+```
+$ source .venv/bin/activate
+$ python3 -m pytest -q
+106 passed in 0.06s
+```
+
+（不激活任何环境、直接用系统 `python3 -m pytest` 会因为 `perceptkit` 没装
+而 `ModuleNotFoundError`——这是预期的：测试文件里的手写 `sys.path` bootstrap
+已按任务要求删除，proper packaging 意味着"先装包，再测"，不是"从任意
+目录躲开安装步骤"。）
+
+## 9. 其他留意点
+
+- `examples/` 目录在任务开始前就已存在但是空的，未处理（任务没要求写
+  quickstart 示例；memgarden 有一个 `examples/quickstart.py`，这个包目前
+  没有）。
+- README.md 是本次新写的（任务清单没明确列出，但 `pyproject.toml` 的
+  `readme = "README.md"` 字段引用它，`uv sync` 会因为它存在而不报错；
+  没写的话仍能跑 pytest，但 `hatchling` 打包会失败）。内容参照 memgarden
+  README 的结构（做什么/不做什么 -> 最小代码 -> 目录），但篇幅大幅压缩。