dsh-retraction-watch 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (61) hide show
  1. package/CHANGELOG.md +47 -0
  2. package/LICENSE +201 -0
  3. package/README-zh.md +112 -0
  4. package/README.md +111 -2
  5. package/cordis.patch.yml +19 -0
  6. package/lib/config.d.ts +45 -0
  7. package/lib/config.d.ts.map +1 -0
  8. package/lib/config.js +61 -0
  9. package/lib/config.js.map +1 -0
  10. package/lib/http.d.ts +51 -0
  11. package/lib/http.d.ts.map +1 -0
  12. package/lib/http.js +112 -0
  13. package/lib/http.js.map +1 -0
  14. package/lib/index.d.ts +38 -0
  15. package/lib/index.d.ts.map +1 -0
  16. package/lib/index.js +51 -0
  17. package/lib/index.js.map +1 -0
  18. package/lib/report.d.ts +10 -0
  19. package/lib/report.d.ts.map +1 -0
  20. package/lib/report.js +43 -0
  21. package/lib/report.js.map +1 -0
  22. package/lib/retraction.d.ts +73 -0
  23. package/lib/retraction.d.ts.map +1 -0
  24. package/lib/retraction.js +135 -0
  25. package/lib/retraction.js.map +1 -0
  26. package/lib/runtime.d.ts +98 -0
  27. package/lib/runtime.d.ts.map +1 -0
  28. package/lib/runtime.js +346 -0
  29. package/lib/runtime.js.map +1 -0
  30. package/lib/tools/retraction-check.d.ts +12 -0
  31. package/lib/tools/retraction-check.d.ts.map +1 -0
  32. package/lib/tools/retraction-check.js +108 -0
  33. package/lib/tools/retraction-check.js.map +1 -0
  34. package/lib/tools/retraction-report.d.ts +10 -0
  35. package/lib/tools/retraction-report.d.ts.map +1 -0
  36. package/lib/tools/retraction-report.js +50 -0
  37. package/lib/tools/retraction-report.js.map +1 -0
  38. package/lib/tools/retraction-watch.d.ts +12 -0
  39. package/lib/tools/retraction-watch.d.ts.map +1 -0
  40. package/lib/tools/retraction-watch.js +78 -0
  41. package/lib/tools/retraction-watch.js.map +1 -0
  42. package/lib/tools/shared.d.ts +47 -0
  43. package/lib/tools/shared.d.ts.map +1 -0
  44. package/lib/tools/shared.js +27 -0
  45. package/lib/tools/shared.js.map +1 -0
  46. package/lib/version.d.ts +7 -0
  47. package/lib/version.d.ts.map +1 -0
  48. package/lib/version.js +7 -0
  49. package/lib/version.js.map +1 -0
  50. package/package.json +80 -4
  51. package/src/config.ts +94 -0
  52. package/src/http.ts +144 -0
  53. package/src/index.ts +67 -0
  54. package/src/report.ts +45 -0
  55. package/src/retraction.ts +172 -0
  56. package/src/runtime.ts +415 -0
  57. package/src/tools/retraction-check.ts +106 -0
  58. package/src/tools/retraction-report.ts +52 -0
  59. package/src/tools/retraction-watch.ts +75 -0
  60. package/src/tools/shared.ts +28 -0
  61. package/src/version.ts +7 -0
package/CHANGELOG.md ADDED
@@ -0,0 +1,47 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project are documented here. The format follows
4
+ [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
5
+ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
6
+
7
+ ## [Unreleased]
8
+
9
+ ### Fixed
10
+
11
+ - Re-checking the same Crossref answers no longer fails with `STORE_ERROR`:
12
+ evidence identity includes the checks and retrieval times come from the
13
+ immutable snapshots, so unchanged answers dedupe.
14
+ - The first observation of a DOI is no longer reported as `changed: true`:
15
+ `changed` now requires a recorded previous status that differs, matching the
16
+ tool description.
17
+ - A transient update-query 5xx was cached for the full TTL and replayed as
18
+ `unknown`; only 2xx/3xx answers are cached now.
19
+ - `mailto` was documented as the Crossref polite-pool contact but never sent.
20
+ It is now added to both Crossref requests and stripped from cached/stored
21
+ URLs so the address does not leak into evidence.
22
+ - `package.json#author` said `dsh-statcheck contributors`.
23
+
24
+ ## [0.1.0] - 2026-11-08
25
+
26
+ First release: retraction and correction monitoring.
27
+
28
+ ### Added
29
+
30
+ - `retraction_check`: per-DOI status from two **verified** Crossref queries
31
+ (`/works/{doi}` and `/works?filter=updates:{doi}`), with notice DOIs,
32
+ expression-of-concern/correction distinction, and REP evidence holding both
33
+ provider responses.
34
+ - `retraction_watch`: bounded-concurrency bibliography check with an
35
+ append-only timeline and change detection (`clear → retracted`).
36
+ - `retraction_report`: Markdown + SARIF 2.1.0.
37
+ - `clear` carries an explicit absence-of-evidence caveat; `unknown` is never
38
+ collapsed into `clear`; a failed update query is a `skipped` check.
39
+ - Bounded HTTP client (allowlist, manual redirect re-validation, timeout,
40
+ interval, retry) with an injectable fetch for offline tests.
41
+ - 23 tests; manual sample table in the README.
42
+
43
+ ### Notes
44
+
45
+ - Retraction Watch ingestion is out of scope in v0.1 (licence/coverage review
46
+ required first).
47
+ - No scheduler: the caller decides when to poll.
package/LICENSE ADDED
@@ -0,0 +1,201 @@
1
+ Apache License
2
+ Version 2.0, January 2004
3
+ http://www.apache.org/licenses/
4
+
5
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6
+
7
+ 1. Definitions.
8
+
9
+ "License" shall mean the terms and conditions for use, reproduction,
10
+ and distribution as defined by Sections 1 through 9 of this document.
11
+
12
+ "Licensor" shall mean the copyright owner or entity authorized by
13
+ the copyright owner that is granting the License.
14
+
15
+ "Legal Entity" shall mean the union of the acting entity and all
16
+ other entities that control, are controlled by, or are under common
17
+ control with that entity. For the purposes of this definition,
18
+ "control" means (i) the power, direct or indirect, to cause the
19
+ direction or management of such entity, whether by contract or
20
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
21
+ outstanding shares, or (iii) beneficial ownership of such entity.
22
+
23
+ "You" (or "Your") shall mean an individual or Legal Entity
24
+ exercising permissions granted by this License.
25
+
26
+ "Source" form shall mean the preferred form for making modifications,
27
+ including but not limited to software source code, documentation
28
+ source, and configuration files.
29
+
30
+ "Object" form shall mean any form resulting from mechanical
31
+ transformation or translation of a Source form, including but
32
+ not limited to compiled object code, generated documentation,
33
+ and conversions to other media types.
34
+
35
+ "Work" shall mean the work of authorship, whether in Source or
36
+ Object form, made available under the License, as indicated by a
37
+ copyright notice that is included in or attached to the work
38
+ (an example is provided in the Appendix below).
39
+
40
+ "Derivative Works" shall mean any work, whether in Source or Object
41
+ form, that is based on (or derived from) the Work and for which the
42
+ editorial revisions, annotations, elaborations, or other modifications
43
+ represent, as a whole, an original work of authorship. For the purposes
44
+ of this License, Derivative Works shall not include works that remain
45
+ separable from, or merely link (or bind by name) to the interfaces of,
46
+ the Work and Derivative Works thereof.
47
+
48
+ "Contribution" shall mean any work of authorship, including
49
+ the original version of the Work and any modifications or additions
50
+ to that Work or Derivative Works thereof, that is intentionally
51
+ submitted to Licensor for inclusion in the Work by the copyright owner
52
+ or by an individual or Legal Entity authorized to submit on behalf of
53
+ the copyright owner. For the purposes of this definition, "submitted"
54
+ means any form of electronic, verbal, or written communication sent
55
+ to the Licensor or its representatives, including but not limited to
56
+ communication on electronic mailing lists, source code control systems,
57
+ and issue tracking systems that are managed by, or on behalf of, the
58
+ Licensor for the purpose of discussing and improving the Work, but
59
+ excluding communication that is conspicuously marked or otherwise
60
+ designated in writing by the copyright owner as "Not a Contribution."
61
+
62
+ "Contributor" shall mean Licensor and any individual or Legal Entity
63
+ on behalf of whom a Contribution has been received by Licensor and
64
+ subsequently incorporated within the Work.
65
+
66
+ 2. Grant of Copyright License. Subject to the terms and conditions of
67
+ this License, each Contributor hereby grants to You a perpetual,
68
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
69
+ copyright license to reproduce, prepare Derivative Works of,
70
+ publicly display, publicly perform, sublicense, and distribute the
71
+ Work and such Derivative Works in Source or Object form.
72
+
73
+ 3. Grant of Patent License. Subject to the terms and conditions of
74
+ this License, each Contributor hereby grants to You a perpetual,
75
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
76
+ (except as stated in this section) patent license to make, have made,
77
+ use, offer to sell, sell, import, and otherwise transfer the Work,
78
+ where such license applies only to those patent claims licensable
79
+ by such Contributor that are necessarily infringed by their
80
+ Contribution(s) alone or by combination of their Contribution(s)
81
+ with the Work to which such Contribution(s) was submitted. If You
82
+ institute patent litigation against any entity (including a
83
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
84
+ or a Contribution incorporated within the Work constitutes direct
85
+ or contributory patent infringement, then any patent licenses
86
+ granted to You under this License for that Work shall terminate
87
+ as of the date such litigation is filed.
88
+
89
+ 4. Redistribution. You may reproduce and distribute copies of the
90
+ Work or Derivative Works thereof in any medium, with or without
91
+ modifications, and in Source or Object form, provided that You
92
+ meet the following conditions:
93
+
94
+ (a) You must give any other recipients of the Work or
95
+ Derivative Works a copy of this License; and
96
+
97
+ (b) You must cause any modified files to carry prominent notices
98
+ stating that You changed the files; and
99
+
100
+ (c) You must retain, in the Source form of any Derivative Works
101
+ that You distribute, all copyright, patent, trademark, and
102
+ attribution notices from the Source form of the Work,
103
+ excluding those notices that do not pertain to any part of
104
+ the Derivative Works; and
105
+
106
+ (d) If the Work includes a "NOTICE" text file as part of its
107
+ distribution, then any Derivative Works that You distribute must
108
+ include a readable copy of the attribution notices contained
109
+ within such NOTICE file, excluding those notices that do not
110
+ pertain to any part of the Derivative Works, in at least one
111
+ of the following places: within a NOTICE text file distributed
112
+ as part of the Derivative Works; within the Source form or
113
+ documentation, if provided along with the Derivative Works; or,
114
+ within a display generated by the Derivative Works, if and
115
+ wherever such third-party notices normally appear. The contents
116
+ of the NOTICE file are for informational purposes only and
117
+ do not modify the License. You may add Your own attribution
118
+ notices within Derivative Works that You distribute, alongside
119
+ or as an addendum to the NOTICE text from the Work, provided
120
+ that such additional attribution notices cannot be construed
121
+ as modifying the License.
122
+
123
+ You may add Your own copyright statement to Your modifications and
124
+ may provide additional or different license terms and conditions
125
+ for use, reproduction, or distribution of Your modifications, or
126
+ for any such Derivative Works as a whole, provided Your use,
127
+ reproduction, and distribution of the Work otherwise complies with
128
+ the conditions stated in this License.
129
+
130
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
131
+ any Contribution intentionally submitted for inclusion in the Work
132
+ by You to the Licensor shall be under the terms and conditions of
133
+ this License, without any additional terms or conditions.
134
+ Notwithstanding the above, nothing herein shall supersede or modify
135
+ the terms of any separate license agreement you may have executed
136
+ with Licensor regarding such Contributions.
137
+
138
+ 6. Trademarks. This License does not grant permission to use the trade
139
+ names, trademarks, service marks, or product names of the Licensor,
140
+ except as required for reasonable and customary use in describing the
141
+ origin of the Work and reproducing the content of the NOTICE file.
142
+
143
+ 7. Disclaimer of Warranty. Unless required by applicable law or
144
+ agreed to in writing, Licensor provides the Work (and each
145
+ Contributor provides its Contributions) on an "AS IS" BASIS,
146
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
147
+ implied, including, without limitation, any warranties or conditions
148
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
149
+ PARTICULAR PURPOSE. You are solely responsible for determining the
150
+ appropriateness of using or redistributing the Work and assume any
151
+ risks associated with Your exercise of permissions under this License.
152
+
153
+ 8. Limitation of Liability. In no event and under no legal theory,
154
+ whether in tort (including negligence), contract, or otherwise,
155
+ unless required by applicable law (such as deliberate and grossly
156
+ negligent acts) or agreed to in writing, shall any Contributor be
157
+ liable to You for damages, including any direct, indirect, special,
158
+ incidental, or consequential damages of any character arising as a
159
+ result of this License or out of the use or inability to use the
160
+ Work (including but not limited to damages for loss of goodwill,
161
+ work stoppage, computer failure or malfunction, or any and all
162
+ other commercial damages or losses), even if such Contributor
163
+ has been advised of the possibility of such damages.
164
+
165
+ 9. Accepting Warranty or Additional Liability. While redistributing
166
+ the Work or Derivative Works thereof, You may choose to offer,
167
+ and charge a fee for, acceptance of support, warranty, indemnity,
168
+ or other liability obligations and/or rights consistent with this
169
+ License. However, in accepting such obligations, You may act only
170
+ on Your own behalf and on Your sole responsibility, not on behalf
171
+ of any other Contributor, and only if You agree to indemnify,
172
+ defend, and hold each Contributor harmless for any liability
173
+ incurred by, or claims asserted against, such Contributor by reason
174
+ of your accepting any such warranty or additional liability.
175
+
176
+ END OF TERMS AND CONDITIONS
177
+
178
+ APPENDIX: How to apply the Apache License to your work.
179
+
180
+ To apply the Apache License to your work, attach the following
181
+ boilerplate notice, with the fields enclosed by brackets "[]"
182
+ replaced with your own identifying information. (Don't include
183
+ the brackets!) The text should be enclosed in the appropriate
184
+ comment syntax for the file format. We also recommend that a
185
+ file or class name and description of purpose be included on the
186
+ same "printed page" as the copyright notice for easier
187
+ identification within third-party archives.
188
+
189
+ Copyright [yyyy] [name of copyright owner]
190
+
191
+ Licensed under the Apache License, Version 2.0 (the "License");
192
+ you may not use this file except in compliance with the License.
193
+ You may obtain a copy of the License at
194
+
195
+ http://www.apache.org/licenses/LICENSE-2.0
196
+
197
+ Unless required by applicable law or agreed to in writing, software
198
+ distributed under the License is distributed on an "AS IS" BASIS,
199
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
200
+ See the License for the specific language governing permissions and
201
+ limitations under the License.
package/README-zh.md ADDED
@@ -0,0 +1,112 @@
1
+ # dsh-retraction-watch
2
+
3
+ **你引用的论文,后来有没有被撤稿或更正?**
4
+
5
+ *Crossref 工作记录 + 已实测的 `filter=updates:<doi>` 查询、逐 DOI 状态、可见变化的追加式时间线,以及可复读的 REP 证据。`clear` 只表示没有登记在册的通知,绝不是“这篇论文没问题”。*
6
+
7
+ [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
8
+ [![Node](https://img.shields.io/badge/node-%5E22.19%20%7C%7C%20%3E%3D24.9-brightgreen.svg)]()
9
+
10
+ [English](README.md) · 简体中文
11
+
12
+ ---
13
+
14
+ ## 它做什么
15
+
16
+ - `retraction_check(doi)` → `retracted` / `concern` / `corrected` / `notice` / `clear` / `unknown`,并附通知 DOI,以及一条包含两次 Crossref 响应的 REP 证据记录。
17
+ - `retraction_watch(dois)` → 对一份参考文献列表做同样的检查,并**检测变化**:时间线记录每一次观察到的状态,因此“clear → retracted”会作为变化报出。
18
+ - `retraction_report(items)` → Markdown 表格 + SARIF 2.1.0(撤稿/关注 = error,更正 = warning)。
19
+
20
+ ## 已验证的数据源能力(不是猜的)
21
+
22
+ | 查询 | 结果 |
23
+ |---|---|
24
+ | `GET /works/{doi}` | 被引用的工作;若其中带有 `update-to`,说明这个 DOI 本身就是一条通知 |
25
+ | `GET /works?filter=updates:{doi}` | 更新该 DOI 的工作 —— **实测可用,HTTP 200**(2026-11-08) |
26
+ | `GET /works?filter=update-to:{doi}` | **不存在**,HTTP 400 |
27
+ | `filter=relation.type:is-retracted-by` | **不是合法的 relation type**,HTTP 400 |
28
+
29
+ 插件只使用这两条可用的查询。更新查询失败时,报告 `unknown` 和一项 `skipped` 检查 —— 绝不会报 `clear`。
30
+
31
+ ## 状态含义
32
+
33
+ | 状态 | 含义 |
34
+ |---|---|
35
+ | `retracted` | 有撤稿通知指向该 DOI |
36
+ | `concern` | 有关注声明指向它 |
37
+ | `corrected` | 有更正通知指向它 |
38
+ | `notice` | 有其他类型的更新通知指向它 |
39
+ | `clear` | Crossref **没有登记**更新通知 |
40
+ | `unknown` | DOI 不在 Crossref,或查询失败 |
41
+
42
+ `clear` 表示“没有证据”,而不是“证据表明有效”:Crossref 通知可能滞后于发表,而且 v0.1 **不查询** Retraction Watch 的覆盖范围。`unknown` 永远不会被并入 `clear`。
43
+
44
+ ## 它不做什么
45
+
46
+ - **不接入 Retraction Watch**(接入前需先核对许可与覆盖范围)。
47
+ - **不做质量判断**:有更正不代表论文有错,撤稿理由也不作评估。
48
+ - **不做抓取**:除这两条 Crossref 查询外不再抓取其他内容;不碰 CNKI,也不碰 Sci-Hub。
49
+ - **不做定时运行**:每次调用工具时才更新时间线;调度由宿主(`dsh-jobs`)或用户负责。
50
+
51
+ ## 兼容性与安装
52
+
53
+ | | |
54
+ |---|---|
55
+ | DeepSeek Harness | **`dsh-v0.2.1-rc.5`**(2026-11-08 实测);peer `>=0.2.1-0 <0.3.0 \|\| >=0.2.2-0 <0.3.0` |
56
+ | Node | `^22.19.0 \|\| >=24.9.0`(实测 `24.22.1`),仅 ESM |
57
+ | Peer 依赖 | `@perrylink/dsh-research-core ^0.1.0`、`@deepseek-ai/cordis ^4.0.5-alpha.1`、`@deepseek-ai/dsh-tools`、`@deepseek-ai/schemastery ^3.18.5-alpha.1` |
58
+ | 运行时依赖 | **零** |
59
+
60
+ ```sh
61
+ dsh plugin --profile <name> add @perrylink/dsh-research-core dsh-retraction-watch
62
+ dsh --profile <name> --dump-config | grep dsh-retraction-watch
63
+ ```
64
+
65
+ ## 配置
66
+
67
+ | 键 | 默认值 | 含义 |
68
+ |---|---|---|
69
+ | `enabled` | `true` | `false` 时不挂载任何内容 |
70
+ | `root` | `.retraction-watch` | 存储、缓存、时间线与记录的根目录 |
71
+ | `userAgent` | `dsh-retraction-watch/0.1.0 (…)` | 发送给 Crossref |
72
+ | `mailto` | — | Crossref polite pool 联系方式(可选) |
73
+ | `timeoutMs` | `15000` | 单次请求的超时 |
74
+ | `minIntervalMs` | `150` | 同一 host 的最小间隔 |
75
+ | `retries` / `maxRedirects` | `1` / `3` | 有界的重试与重定向预算 |
76
+ | `cacheTtlMs` | `604800000` | 响应缓存(7 天;`fresh` 绕过) |
77
+ | `maxBatch` / `batchConcurrency` | `50` / `3` | `retraction_watch` 的上限 |
78
+
79
+ ## 安全边界
80
+
81
+ - 仅使用 HTTPS,采用精确 host 白名单(`api.crossref.org`),URL 中不带凭据,不使用自定义端口。
82
+ - 重定向手动跟随,**每一跳都会重新校验**是否在白名单内。
83
+ - 响应以不可变快照形式存储;证据只记录 URL,绝不记录密钥。
84
+ - 缓存响应是尽力而为:缓存失败只算未命中,绝不作为检查结果。
85
+
86
+ ## 评测
87
+
88
+ **23 个测试**,分布在三个文件:更新类型映射、通知过滤、聚合状态优先级、检查构造(clear / retracted / unknown / 网络失败)、运行时(撤稿、带保留说明的 clear、404 → unknown、更新查询失败 → unknown、更正、非法 DOI、重复核查不产生证据冲突、瞬时 5xx 不写入缓存、polite pool 联系方式不写入已存证据)、跨三次运行的时间线变化检测(首次观察不算变化)、批量逐项隔离、批量上限、工具 schema/渲染器、包契约。
89
+
90
+ 人工样例集(本插件不声称基准测试结果;其正确性来自 Crossref 契约,而不是学习得到的判定):
91
+
92
+ | 场景 | 预期 | 覆盖 |
93
+ |---|---|---|
94
+ | 有撤稿通知指向该 DOI | `retracted`,检查 `fail` | 测试 |
95
+ | 有更正通知 | `corrected`,检查 `warn` | 测试 |
96
+ | 有关注声明 | `concern`,检查 `fail` | 测试 |
97
+ | 无通知 | `clear` + 无通知说明 | 测试 |
98
+ | DOI 不在 Crossref | `unknown`,`not_found` skipped | 测试 |
99
+ | 更新查询 5xx | `unknown`,`network_error` skipped | 测试 |
100
+ | 两次运行之间状态变化 | `changed: true`、`previousStatus` | 测试 |
101
+ | 首次观察某个 DOI | `changed: false`,无 `previousStatus` | 测试 |
102
+
103
+ ## 已知限制(v0.1)
104
+
105
+ - 不查询 Retraction Watch 数据,仅覆盖 Crossref。
106
+ - 没有 Crossref `update-to` 链接的通知在此不可见。
107
+ - 时间线是追加式 JSONL,不做压缩合并;书目很大时需手工裁剪。
108
+ - 没有邮件/webhook 告警;轮询必须由调用方驱动。
109
+
110
+ ## 许可
111
+
112
+ Apache-2.0。运行时不含第三方代码。
package/README.md CHANGED
@@ -1,3 +1,112 @@
1
- # Temporary Holding Version
1
+ # dsh-retraction-watch
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ **Has anything been published against the papers you cite?**
4
+
5
+ *Crossref work records + the verified `filter=updates:<doi>` query, a per-DOI status, an append-only timeline that shows changes, and REP evidence you can re-read. `clear` means no registered notice — never "this paper is valid".*
6
+
7
+ [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
8
+ [![Node](https://img.shields.io/badge/node-%5E22.19%20%7C%7C%20%3E%3D24.9-brightgreen.svg)]()
9
+
10
+ English · [简体中文](README-zh.md)
11
+
12
+ ---
13
+
14
+ ## What it does
15
+
16
+ - `retraction_check(doi)` → `retracted` / `concern` / `corrected` / `notice` / `clear` / `unknown`, with the notice DOIs and a REP evidence record holding both Crossref responses.
17
+ - `retraction_watch(dois)` → the same for a bibliography, with **change detection**: the timeline records every observed status, so "clear → retracted" is reported as a change.
18
+ - `retraction_report(items)` → Markdown table + SARIF 2.1.0 (retractions/concerns = errors, corrections = warnings).
19
+
20
+ ## Verified provider capability (not guessed)
21
+
22
+ | Query | Result |
23
+ |---|---|
24
+ | `GET /works/{doi}` | the cited work; if it carries `update-to`, the DOI *is* a notice |
25
+ | `GET /works?filter=updates:{doi}` | works that update this DOI — **verified live, HTTP 200** (2026-11-08) |
26
+ | `GET /works?filter=update-to:{doi}` | **does not exist**, HTTP 400 |
27
+ | `filter=relation.type:is-retracted-by` | **not a valid relation type**, HTTP 400 |
28
+
29
+ The plugin only uses the two working queries. When the update query fails it reports `unknown` and a `skipped` check — never `clear`.
30
+
31
+ ## Status meanings
32
+
33
+ | Status | Meaning |
34
+ |---|---|
35
+ | `retracted` | a retraction notice points at this DOI |
36
+ | `concern` | an expression of concern points at it |
37
+ | `corrected` | a correction notice points at it |
38
+ | `notice` | an update notice of another type points at it |
39
+ | `clear` | Crossref has **no registered** update notice |
40
+ | `unknown` | the DOI is not in Crossref, or the lookup failed |
41
+
42
+ `clear` is absence of evidence, not evidence of validity: Crossref notices can lag publication, and Retraction Watch coverage is **not** queried in v0.1. `unknown` is never collapsed into `clear`.
43
+
44
+ ## What it does not do
45
+
46
+ - **No Retraction Watch ingestion** (licence/coverage to be checked before that step).
47
+ - **No quality judgement**: a correction does not make a paper wrong, and a retraction's reasons are not evaluated.
48
+ - **No scraping** beyond the two Crossref queries; no CNKI, no Sci-Hub.
49
+ - **No scheduled runner**: the timeline is updated whenever the tool is called; scheduling belongs to the host (`dsh-jobs`) or the user.
50
+
51
+ ## Compatibility & install
52
+
53
+ | | |
54
+ |---|---|
55
+ | DeepSeek Harness | **`dsh-v0.2.1-rc.5`** (verified 2026-11-08); peer `>=0.2.1-0 <0.3.0 \|\| >=0.2.2-0 <0.3.0` |
56
+ | Node | `^22.19.0 \|\| >=24.9.0` (tested `24.22.1`), ESM only |
57
+ | Peers | `@perrylink/dsh-research-core ^0.1.0`, `@deepseek-ai/cordis ^4.0.5-alpha.1`, `@deepseek-ai/dsh-tools`, `@deepseek-ai/schemastery ^3.18.5-alpha.1` |
58
+ | Runtime dependencies | **zero** |
59
+
60
+ ```sh
61
+ dsh plugin --profile <name> add @perrylink/dsh-research-core dsh-retraction-watch
62
+ dsh --profile <name> --dump-config | grep dsh-retraction-watch
63
+ ```
64
+
65
+ ## Configuration
66
+
67
+ | Key | Default | Meaning |
68
+ |---|---|---|
69
+ | `enabled` | `true` | `false` mounts nothing |
70
+ | `root` | `.retraction-watch` | store, cache, timeline and records root |
71
+ | `userAgent` | `dsh-retraction-watch/0.1.0 (…)` | sent to Crossref |
72
+ | `mailto` | — | Crossref polite-pool contact (optional) |
73
+ | `timeoutMs` | `15000` | per-request deadline |
74
+ | `minIntervalMs` | `150` | per-host interval |
75
+ | `retries` / `maxRedirects` | `1` / `3` | bounded retry and redirect budget |
76
+ | `cacheTtlMs` | `604800000` | response cache (7 days; `fresh` bypasses) |
77
+ | `maxBatch` / `batchConcurrency` | `50` / `3` | `retraction_watch` bounds |
78
+
79
+ ## Security boundaries
80
+
81
+ - HTTPS only, exact-host allowlist (`api.crossref.org`), no credentials in URLs, no custom ports.
82
+ - Redirects are followed manually and **each hop is re-validated** against the allowlist.
83
+ - Responses are stored as immutable snapshots; the evidence records URLs, never secrets.
84
+ - Cached responses are best-effort: a cache failure is a miss, never a check result.
85
+
86
+ ## Evaluation
87
+
88
+ **23 tests** across three files: update-type mapping, notice filtering, aggregate status precedence, check construction (clear / retracted / unknown / network failure), runtime (retraction, clear with caveat, 404 → unknown, failed update query → unknown, correction, invalid DOI, re-check without an evidence conflict, no caching of a transient 5xx, polite-pool contact kept out of stored evidence), timeline change detection across three runs (the first observation is not a change), per-item batch isolation, batch cap, tool schemas/renderers, package contract.
89
+
90
+ Manual sample set (no benchmark is claimed for this plugin; its correctness is the Crossref contract, not a learned decision):
91
+
92
+ | Scenario | Expected | Covered by |
93
+ |---|---|---|
94
+ | retraction notice points at the DOI | `retracted`, check `fail` | test |
95
+ | correction notice | `corrected`, check `warn` | test |
96
+ | expression of concern | `concern`, check `fail` | test |
97
+ | no notices | `clear` + absence caveat | test |
98
+ | DOI not in Crossref | `unknown`, `not_found` skipped | test |
99
+ | update query 5xx | `unknown`, `network_error` skipped | test |
100
+ | status changes between runs | `changed: true`, `previousStatus` | test |
101
+ | first observation of a DOI | `changed: false`, no `previousStatus` | test |
102
+
103
+ ## Known limitations (v0.1)
104
+
105
+ - Retraction Watch data is not queried; Crossref-only coverage.
106
+ - A notice published without a Crossref `update-to` link is invisible here.
107
+ - The timeline is append-only JSONL with no compaction; prune manually for very large bibliographies.
108
+ - No email/webhook alerts; polling must be driven by the caller.
109
+
110
+ ## License
111
+
112
+ Apache-2.0. No third-party runtime code.
@@ -0,0 +1,19 @@
1
+ # dsh-retraction-watch bundle patch: mount the retraction/correction tools.
2
+ #
3
+ # Every key below is a Config field (Schemastery schema); invalid values fail the
4
+ # profile load loudly. Only Crossref is contacted, over HTTPS, with an explicit
5
+ # timeout and per-host interval.
6
+ - insert:
7
+ - id: dsh-retraction-watch
8
+ name: dsh-retraction-watch
9
+ config:
10
+ enabled: true
11
+ root: .retraction-watch
12
+ userAgent: dsh-retraction-watch/0.1.0 (https://github.com/PerryLink/dsh-retraction-watch)
13
+ timeoutMs: 15000
14
+ minIntervalMs: 150
15
+ retries: 1
16
+ maxRedirects: 3
17
+ cacheTtlMs: 604800000
18
+ maxBatch: 50
19
+ batchConcurrency: 3
@@ -0,0 +1,45 @@
1
+ /**
2
+ * Config schema and resolution for `dsh-retraction-watch`.
3
+ * @module dsh-retraction-watch/config
4
+ */
5
+ import z from '@deepseek-ai/schemastery';
6
+ /** Raw plugin config. */
7
+ export interface Config {
8
+ enabled?: boolean;
9
+ /** Store/record root. */
10
+ root?: string;
11
+ /** User-Agent sent to Crossref (include a contact address at scale). */
12
+ userAgent?: string;
13
+ /** Contact address (Crossref polite pool). */
14
+ mailto?: string;
15
+ timeoutMs?: number;
16
+ minIntervalMs?: number;
17
+ retries?: number;
18
+ maxRedirects?: number;
19
+ cacheTtlMs?: number;
20
+ maxBatch?: number;
21
+ batchConcurrency?: number;
22
+ }
23
+ /** Fully resolved config. */
24
+ export interface ResolvedConfig {
25
+ readonly enabled: boolean;
26
+ readonly root: string;
27
+ readonly userAgent: string;
28
+ readonly mailto: string | undefined;
29
+ readonly timeoutMs: number;
30
+ readonly minIntervalMs: number;
31
+ readonly retries: number;
32
+ readonly maxRedirects: number;
33
+ readonly cacheTtlMs: number;
34
+ readonly maxBatch: number;
35
+ readonly batchConcurrency: number;
36
+ }
37
+ /** Schemastery schema. */
38
+ export declare const Config: z<Config>;
39
+ /**
40
+ * Validate raw values and fill explicit defaults.
41
+ * @param config - raw plugin config.
42
+ * @returns the fully resolved config.
43
+ */
44
+ export declare function resolveConfig(config?: Config): ResolvedConfig;
45
+ //# sourceMappingURL=config.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,CAAC,MAAM,0BAA0B,CAAA;AAExC,yBAAyB;AACzB,MAAM,WAAW,MAAM;IACrB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,yBAAyB;IACzB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,8CAA8C;IAC9C,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAC1B;AAED,6BAA6B;AAC7B,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;IACnC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;CAClC;AAED,0BAA0B;AAC1B,eAAO,MAAM,MAAM,EAAE,CAAC,CAAC,MAAM,CAY3B,CAAA;AAOF;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,GAAE,MAAW,GAAG,cAAc,CA2BjE"}
package/lib/config.js ADDED
@@ -0,0 +1,61 @@
1
+ /**
2
+ * Config schema and resolution for `dsh-retraction-watch`.
3
+ * @module dsh-retraction-watch/config
4
+ */
5
+ import path from 'node:path';
6
+ import z from '@deepseek-ai/schemastery';
7
+ /** Schemastery schema. */
8
+ export const Config = z.object({
9
+ enabled: z.boolean().default(true),
10
+ root: z.string().default('.retraction-watch'),
11
+ userAgent: z.string().default('dsh-retraction-watch/0.1.0 (https://github.com/PerryLink/dsh-retraction-watch)'),
12
+ mailto: z.string(),
13
+ timeoutMs: z.number().default(15_000),
14
+ minIntervalMs: z.number().default(150),
15
+ retries: z.number().default(1),
16
+ maxRedirects: z.number().default(3),
17
+ cacheTtlMs: z.number().default(7 * 24 * 60 * 60 * 1000),
18
+ maxBatch: z.number().default(50),
19
+ batchConcurrency: z.number().default(3),
20
+ });
21
+ /** Throw unless the value is a non-negative safe integer. */
22
+ function assertNonNegativeInt(name, value) {
23
+ if (!Number.isSafeInteger(value) || value < 0)
24
+ throw new TypeError(`${name} must be a non-negative safe integer, got ${String(value)}`);
25
+ }
26
+ /**
27
+ * Validate raw values and fill explicit defaults.
28
+ * @param config - raw plugin config.
29
+ * @returns the fully resolved config.
30
+ */
31
+ export function resolveConfig(config = {}) {
32
+ const root = config.root ?? '.retraction-watch';
33
+ if (typeof root !== 'string' || root.trim() === '')
34
+ throw new TypeError('root must be a non-empty path');
35
+ const timeoutMs = config.timeoutMs ?? 15_000;
36
+ const minIntervalMs = config.minIntervalMs ?? 150;
37
+ const retries = config.retries ?? 1;
38
+ const maxRedirects = config.maxRedirects ?? 3;
39
+ const cacheTtlMs = config.cacheTtlMs ?? 7 * 24 * 60 * 60 * 1000;
40
+ const maxBatch = config.maxBatch ?? 50;
41
+ const batchConcurrency = config.batchConcurrency ?? 3;
42
+ for (const [name, value] of Object.entries({ timeoutMs, minIntervalMs, retries, maxRedirects, cacheTtlMs, maxBatch, batchConcurrency })) {
43
+ assertNonNegativeInt(name, value);
44
+ }
45
+ if (timeoutMs <= 0 || maxBatch <= 0 || batchConcurrency <= 0)
46
+ throw new TypeError('timeoutMs, maxBatch and batchConcurrency must be positive');
47
+ return {
48
+ enabled: config.enabled ?? true,
49
+ root: path.resolve(root),
50
+ userAgent: config.userAgent ?? 'dsh-retraction-watch/0.1.0 (https://github.com/PerryLink/dsh-retraction-watch)',
51
+ ...(config.mailto === undefined || config.mailto.trim() === '' ? { mailto: undefined } : { mailto: config.mailto }),
52
+ timeoutMs,
53
+ minIntervalMs,
54
+ retries,
55
+ maxRedirects,
56
+ cacheTtlMs,
57
+ maxBatch,
58
+ batchConcurrency,
59
+ };
60
+ }
61
+ //# sourceMappingURL=config.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}
package/lib/http.d.ts ADDED
@@ -0,0 +1,51 @@
1
+ /**
2
+ * Bounded HTTP client for Crossref (HTTPS, exact-host allowlist, manual
3
+ * redirect re-validation, timeout, per-host interval, one retry on 429/503).
4
+ * The fetch implementation is injectable so tests never touch the network.
5
+ * @module dsh-retraction-watch/http
6
+ */
7
+ /** The only host this plugin talks to. */
8
+ export declare const ALLOWED_HOSTS: readonly string[];
9
+ /** Stable network failure codes. */
10
+ export type NetworkErrorCode = 'blocked_host' | 'invalid_url' | 'too_many_redirects' | 'timeout' | 'network_error' | 'http_error';
11
+ /** A transport-level failure. */
12
+ export declare class WatchNetworkError extends Error {
13
+ /** Stable code. */
14
+ readonly code: NetworkErrorCode;
15
+ constructor(code: NetworkErrorCode, message: string);
16
+ }
17
+ /** One HTTP response. */
18
+ export interface HttpResponse {
19
+ readonly status: number;
20
+ readonly body: string;
21
+ readonly url: string;
22
+ }
23
+ /** The HTTP surface the runtime depends on. */
24
+ export interface HttpClient {
25
+ get(url: string, options?: {
26
+ readonly accept?: string;
27
+ }): Promise<HttpResponse>;
28
+ }
29
+ /** The minimal fetch shape needed. */
30
+ export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
31
+ /** Options for {@link createHttpClient}. */
32
+ export interface HttpClientOptions {
33
+ readonly fetchImpl?: FetchLike;
34
+ readonly timeoutMs: number;
35
+ readonly minIntervalMs: number;
36
+ readonly retries: number;
37
+ readonly maxRedirects: number;
38
+ readonly userAgent: string;
39
+ readonly allowedHosts?: readonly string[];
40
+ readonly now?: () => number;
41
+ readonly sleep?: (ms: number) => Promise<void>;
42
+ }
43
+ /** Validate a URL against the allowlist. */
44
+ export declare function assertAllowed(url: string, allowedHosts?: readonly string[]): URL;
45
+ /**
46
+ * Create the bounded client.
47
+ * @param options - bounds and injection points.
48
+ * @returns the client.
49
+ */
50
+ export declare function createHttpClient(options: HttpClientOptions): HttpClient;
51
+ //# sourceMappingURL=http.d.ts.map