zotkit 0.5.2__tar.gz → 0.7.0__tar.gz

{zotkit-0.5.2/zotkit.egg-info → zotkit-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zotkit
-Version: 0.5.2
+Version: 0.7.0
 Summary: Headless Zotero library management: Web API CRUD plus direct WebDAV attachment upload/download — no desktop app required
 Author: Shawn
 License-Expression: MIT
@@ -16,6 +16,8 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: pyzotero
 Requires-Dist: httpx
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
 Dynamic: license-file
 
 # zotkit
@@ -37,7 +39,7 @@ server**, zotkit can **upload and download the files themselves** by speaking
 Zotero's WebDAV storage format directly — a capability the Web API itself does not
 provide. The format is documented in [docs/webdav-format.md](docs/webdav-format.md).
 
-Built for servers, scripts, and **LLM agents**: every write is dry-run by default,
+Built for servers, scripts, and **LLM agents**: bulk writes are dry-run by default,
 batched, and version-checked, and you can define a tag taxonomy that is *enforced in
 code* so an agent (or a tired human) can't pollute your library with inconsistent tags.
 
@@ -101,6 +103,8 @@ Optionally, copy [`conventions.example.toml`](conventions.example.toml) to
 ```bash
 zotkit find --title "boson sampling"        # search by title/tag/collection
 zotkit find --tag status:to-read
+zotkit show AB12CD34 EF56GH78               # one line per key (read-only);
+                                            #   --json for the full item data
 
 zotkit create --arxiv 2401.12345            # fetch arXiv metadata, dry-run preview
 zotkit create --arxiv 2401.12345 --apply --tags field:ai   # create + download & attach the PDF
@@ -109,17 +113,26 @@ zotkit create --arxiv 2401.12345 1706.03762 math/0211159 --apply   # batch: one
 zotkit create --doi 10.1038/nature14539     # fetch CrossRef metadata by DOI (no PDF —
                                             #   usually paywalled; attach manually after)
 
-zotkit create --file papers.json            # batch from JSON: dry-run preview
+zotkit create --file papers.json            # batch from JSON: dry-run preview —
+                                            #   flags items already in the library
 zotkit create --file papers.json --apply    # create (dedups by DOI/title)
 zotkit attach --from papers.created.json --all   # upload the PDFs (WebDAV or Zotero
                                                  #   Storage — auto-detected from .env)
 
 zotkit enrich --key AB12CD34 EF56GH78       # fill missing fields on existing items
                                             #   in place (dry-run; --apply to write)
+zotkit enrich --missing abstract --apply    # …or batch: every item missing an
+                                            #   abstract (also --missing doi, --all)
+zotkit audit                                # read-only health report: what's missing
+                                            #   where, stamp hygiene (--json for agents)
+zotkit abstract --key AB12CD34 --source cnki --file abs.txt   # paste an abstract
+                                            #   with provenance (owner's tool)
 
 zotkit attach --key AB12CD34 --pdf paper.pdf     # single attach
 zotkit fetch --key AB12CD34 --out downloads      # download attachments (same auto-detection)
 
+zotkit export --key AB12CD34 EF56GH78 -o refs.bib   # BibTeX; cite key = item key
+
 zotkit tag AB12CD34 topic:qaoa prio:high    # validated against conventions.toml
 zotkit status AB12CD34 read                 # replaces the status: tag
 zotkit move AB12CD34 "Algorithms"           # or "Parent :: Child"; --add keeps old home
@@ -141,6 +154,14 @@ daemon-free CLI — no translation-server). CrossRef requests identify themselve
 to the polite pool with a contact address; that should be reachable, so if you
 distribute a tool built on zotkit, set your own via `ZOTKIT_MAILTO`.
 
+**Duplicates**: `create` checks every candidate against the library by exact DOI and
+by normalized title, and skips the ones already there — that has always been the
+`--apply` behavior, and the dry run now runs the same check up front, printing
+`!! already in library as <KEY> — --apply will skip it (use --no-dedup to force)`
+so you see the collision before writing anything. The apply path names the existing
+item's key in its skip messages too. `--no-dedup` turns the check off and creates
+the item regardless.
+
 **Version of record**: when arXiv reports a *journal* DOI (the paper was formally
 published), `--arxiv` builds the journal record from CrossRef instead of a
 `preprint`: proper item
@@ -159,6 +180,29 @@ gates `enrich --rebuild-record`. Items whose abstract zotkit
 wrote also carry an `abstract-source: arxiv|crossref` line in Extra, naming where
 it actually came from.
 
+### Looking items up: `show` and `export`
+
+`zotkit show K [K …]` is the read-only lookup by item key: one line per key —
+`KEY · itemType · FirstAuthor Year · Title · DOI-or-arXiv-id` — or `--json` for the
+full item data. An unknown key is reported on stderr and the exit code is 1, while
+the remaining keys still print. This deliberately supersedes requests for a
+`find --key` flag and a `verify --manifest` subcommand: verifying a manifest is a
+loop over `show` on the project side, and manifest-file parsing is too
+project-specific to belong in zotkit.
+
+`zotkit export --key K [K …]` emits BibTeX for those items, to stdout or to `-o
+refs.bib`; keys are also accepted on stdin, one per line, so it composes with
+whatever produced them. Every entry's cite key is **always** rewritten to the
+Zotero item key — that is the point of the command: item keys are the identity in
+the manifest model, and author-year cite keys don't join against them. An unknown
+key errors on stderr (exit 1) without stopping the other entries from exporting.
+
+`zotkit fetch` still defaults to `./downloads` and prints the absolute path of every
+file it saves. If you omit `--out` while the current directory sits inside a git
+repository, it warns on stderr and suggests an explicit destination: loose PDF
+copies committed into a repo break a library-of-record setup, where the library is
+the one place a file lives.
+
 ### Enriching existing items
 
 `zotkit enrich --key K [K …]` completes incomplete items — missing abstracts,
@@ -181,6 +225,23 @@ published (journal DOI present) to the journal record **in the same item**:
 itemType, published title/date/venue/volume/pages — with `arXiv: <id>` appended
 to Extra and attachments untouched.
 
+Instead of `--key`, `--all` runs over every top-level scholarly item and
+`--missing abstract` / `--missing doi` (repeatable) over just the gaps —
+batching and arXiv/CrossRef rate limiting stay internal, so no pacing or
+batch-splitting on the caller's side. **`zotkit audit`** is the read-only
+companion: counts and key lists for missing abstracts, missing DOI/arXiv id,
+missing PDF attachments, and `abstract-source` stamp hygiene (`--json` for
+agents).
+
+For text enrich *can't* fetch — CNKI, publisher pages, your own summary —
+**`zotkit abstract --key K --source <slug>`** stores a pasted abstract
+(stdin or `--file`) with provenance: the text is cleaned (hidden tags,
+`&nbsp;`, soft hyphens, hard-wrapped lines) and an `abstract-source: <slug>`
+line records where it came from (`cnki`, `ssrn`, `publisher`, `manual` = your
+own words — any lowercase slug). It is the owner's tool, so unlike enrich it
+may *replace* an existing abstract — but only with `--force`, which also
+rewrites the stamp line in place; all other Extra lines stay untouched.
+
 Item JSON for `zotkit create --file` (a list, one object per reference):
 
 ```json

{zotkit-0.5.2 → zotkit-0.7.0}/README.md

@@ -17,7 +17,7 @@ server**, zotkit can **upload and download the files themselves** by speaking
 Zotero's WebDAV storage format directly — a capability the Web API itself does not
 provide. The format is documented in [docs/webdav-format.md](docs/webdav-format.md).
 
-Built for servers, scripts, and **LLM agents**: every write is dry-run by default,
+Built for servers, scripts, and **LLM agents**: bulk writes are dry-run by default,
 batched, and version-checked, and you can define a tag taxonomy that is *enforced in
 code* so an agent (or a tired human) can't pollute your library with inconsistent tags.
 
@@ -81,6 +81,8 @@ Optionally, copy [`conventions.example.toml`](conventions.example.toml) to
 ```bash
 zotkit find --title "boson sampling"        # search by title/tag/collection
 zotkit find --tag status:to-read
+zotkit show AB12CD34 EF56GH78               # one line per key (read-only);
+                                            #   --json for the full item data
 
 zotkit create --arxiv 2401.12345            # fetch arXiv metadata, dry-run preview
 zotkit create --arxiv 2401.12345 --apply --tags field:ai   # create + download & attach the PDF
@@ -89,17 +91,26 @@ zotkit create --arxiv 2401.12345 1706.03762 math/0211159 --apply   # batch: one
 zotkit create --doi 10.1038/nature14539     # fetch CrossRef metadata by DOI (no PDF —
                                             #   usually paywalled; attach manually after)
 
-zotkit create --file papers.json            # batch from JSON: dry-run preview
+zotkit create --file papers.json            # batch from JSON: dry-run preview —
+                                            #   flags items already in the library
 zotkit create --file papers.json --apply    # create (dedups by DOI/title)
 zotkit attach --from papers.created.json --all   # upload the PDFs (WebDAV or Zotero
                                                  #   Storage — auto-detected from .env)
 
 zotkit enrich --key AB12CD34 EF56GH78       # fill missing fields on existing items
                                             #   in place (dry-run; --apply to write)
+zotkit enrich --missing abstract --apply    # …or batch: every item missing an
+                                            #   abstract (also --missing doi, --all)
+zotkit audit                                # read-only health report: what's missing
+                                            #   where, stamp hygiene (--json for agents)
+zotkit abstract --key AB12CD34 --source cnki --file abs.txt   # paste an abstract
+                                            #   with provenance (owner's tool)
 
 zotkit attach --key AB12CD34 --pdf paper.pdf     # single attach
 zotkit fetch --key AB12CD34 --out downloads      # download attachments (same auto-detection)
 
+zotkit export --key AB12CD34 EF56GH78 -o refs.bib   # BibTeX; cite key = item key
+
 zotkit tag AB12CD34 topic:qaoa prio:high    # validated against conventions.toml
 zotkit status AB12CD34 read                 # replaces the status: tag
 zotkit move AB12CD34 "Algorithms"           # or "Parent :: Child"; --add keeps old home
@@ -121,6 +132,14 @@ daemon-free CLI — no translation-server). CrossRef requests identify themselve
 to the polite pool with a contact address; that should be reachable, so if you
 distribute a tool built on zotkit, set your own via `ZOTKIT_MAILTO`.
 
+**Duplicates**: `create` checks every candidate against the library by exact DOI and
+by normalized title, and skips the ones already there — that has always been the
+`--apply` behavior, and the dry run now runs the same check up front, printing
+`!! already in library as <KEY> — --apply will skip it (use --no-dedup to force)`
+so you see the collision before writing anything. The apply path names the existing
+item's key in its skip messages too. `--no-dedup` turns the check off and creates
+the item regardless.
+
 **Version of record**: when arXiv reports a *journal* DOI (the paper was formally
 published), `--arxiv` builds the journal record from CrossRef instead of a
 `preprint`: proper item
@@ -139,6 +158,29 @@ gates `enrich --rebuild-record`. Items whose abstract zotkit
 wrote also carry an `abstract-source: arxiv|crossref` line in Extra, naming where
 it actually came from.
 
+### Looking items up: `show` and `export`
+
+`zotkit show K [K …]` is the read-only lookup by item key: one line per key —
+`KEY · itemType · FirstAuthor Year · Title · DOI-or-arXiv-id` — or `--json` for the
+full item data. An unknown key is reported on stderr and the exit code is 1, while
+the remaining keys still print. This deliberately supersedes requests for a
+`find --key` flag and a `verify --manifest` subcommand: verifying a manifest is a
+loop over `show` on the project side, and manifest-file parsing is too
+project-specific to belong in zotkit.
+
+`zotkit export --key K [K …]` emits BibTeX for those items, to stdout or to `-o
+refs.bib`; keys are also accepted on stdin, one per line, so it composes with
+whatever produced them. Every entry's cite key is **always** rewritten to the
+Zotero item key — that is the point of the command: item keys are the identity in
+the manifest model, and author-year cite keys don't join against them. An unknown
+key errors on stderr (exit 1) without stopping the other entries from exporting.
+
+`zotkit fetch` still defaults to `./downloads` and prints the absolute path of every
+file it saves. If you omit `--out` while the current directory sits inside a git
+repository, it warns on stderr and suggests an explicit destination: loose PDF
+copies committed into a repo break a library-of-record setup, where the library is
+the one place a file lives.
+
 ### Enriching existing items
 
 `zotkit enrich --key K [K …]` completes incomplete items — missing abstracts,
@@ -161,6 +203,23 @@ published (journal DOI present) to the journal record **in the same item**:
 itemType, published title/date/venue/volume/pages — with `arXiv: <id>` appended
 to Extra and attachments untouched.
 
+Instead of `--key`, `--all` runs over every top-level scholarly item and
+`--missing abstract` / `--missing doi` (repeatable) over just the gaps —
+batching and arXiv/CrossRef rate limiting stay internal, so no pacing or
+batch-splitting on the caller's side. **`zotkit audit`** is the read-only
+companion: counts and key lists for missing abstracts, missing DOI/arXiv id,
+missing PDF attachments, and `abstract-source` stamp hygiene (`--json` for
+agents).
+
+For text enrich *can't* fetch — CNKI, publisher pages, your own summary —
+**`zotkit abstract --key K --source <slug>`** stores a pasted abstract
+(stdin or `--file`) with provenance: the text is cleaned (hidden tags,
+`&nbsp;`, soft hyphens, hard-wrapped lines) and an `abstract-source: <slug>`
+line records where it came from (`cnki`, `ssrn`, `publisher`, `manual` = your
+own words — any lowercase slug). It is the owner's tool, so unlike enrich it
+may *replace* an existing abstract — but only with `--force`, which also
+rewrites the stamp line in place; all other Extra lines stay untouched.
+
 Item JSON for `zotkit create --file` (a list, one object per reference):
 
 ```json

{zotkit-0.5.2 → zotkit-0.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "zotkit"
-version = "0.5.2"
+version = "0.7.0"
 description = "Headless Zotero library management: Web API CRUD plus direct WebDAV attachment upload/download — no desktop app required"
 readme = "README.md"
 license = "MIT"
@@ -20,6 +20,9 @@ classifiers = [
 ]
 dependencies = ["pyzotero", "httpx"]
 
+[project.optional-dependencies]
+dev = ["pytest"]
+
 [project.urls]
 Repository = "https://github.com/oldantique/zotkit"
 Issues = "https://github.com/oldantique/zotkit/issues"

zotkit-0.7.0/tests/test_audit.py

@@ -0,0 +1,51 @@
+"""Offline tests for zotkit.audit bucketing, on a fixture library."""
+import types
+
+from zotkit.audit import audit
+
+
+def _top(key, itype="journalArticle", ab="", extra="", doi="", url=""):
+    return {"key": key, "data": {"itemType": itype, "abstractNote": ab,
+                                 "extra": extra, "DOI": doi, "url": url}}
+
+
+TOPS = [
+    _top("OK111111", ab="a", extra="abstract-source: arxiv", doi="10.1/x"),  # healthy
+    _top("NOABS111", doi="10.1/y"),                                # missing abstract
+    _top("NOID1111", ab="a"),                          # unstamped + missing id
+    _top("ARXID111", extra="arXiv: 2401.00001"),       # id via Extra, missing abstract
+    _top("STALE111", extra="abstract-source: cnki", doi="10.1/z"),  # stale stamp
+    _top("NOTE1111", itype="note"),                    # excluded
+    _top("ATT11111", itype="attachment"),              # excluded
+]
+ATTS = [
+    {"key": "A1", "data": {"itemType": "attachment", "parentItem": "OK111111",
+                           "contentType": "application/pdf"}},
+    {"key": "A2", "data": {"itemType": "attachment", "parentItem": "NOABS111",
+                           "contentType": "text/html"}},
+]
+
+
+def _fixture_zot():
+    return types.SimpleNamespace(z=types.SimpleNamespace(
+        everything=lambda x: x,
+        top=lambda: list(TOPS),
+        items=lambda itemType=None: list(ATTS)))
+
+
+def test_audit_buckets():
+    rep = audit(_fixture_zot())
+    b = rep["buckets"]
+    assert rep["total"] == 5  # notes/attachments excluded
+    assert b["missing-abstract"] == ["NOABS111", "ARXID111", "STALE111"]
+    assert b["missing-identifier"] == ["NOID1111"]
+    # an html attachment does not count as a PDF
+    assert b["missing-pdf"] == ["NOABS111", "NOID1111", "ARXID111", "STALE111"]
+    assert b["unstamped-abstract"] == ["NOID1111"]
+    assert b["stale-stamp"] == ["STALE111"]
+
+
+def test_audit_keys_in_library_order():
+    rep = audit(_fixture_zot())
+    assert rep["keys"] == ["OK111111", "NOABS111", "NOID1111", "ARXID111",
+                           "STALE111"]

zotkit-0.7.0/tests/test_dedup.py

@@ -0,0 +1,154 @@
+"""Offline tests for the create-path dedup predicate: the shared
+`dedup_maps`/`duplicate_key` helper, the existing_key recorded by
+`Zot.create_items`, and the dry-run `!!` notice. No network, no live library —
+the Zotero client is faked."""
+from zotkit.cli import dup_notice
+from zotkit.core import Zot, dedup_maps, duplicate_key
+
+
+def _lib(*rows):
+    """rows: (key, title, DOI) -> pyzotero-shaped top-level items."""
+    return [{"key": k, "data": {"title": t, "DOI": doi, "itemType": "journalArticle"}}
+            for k, t, doi in rows]
+
+
+LIBRARY = _lib(
+    ("AAAA1111", "Attention Is All You Need", "10.5555/ATT"),
+    ("BBBB2222", "Deep Residual Learning, Revisited!", ""),
+    ("CCCC3333", "Some Other Paper", "10.1103/PhysRevLett.116.061102"),
+)
+
+
+# ---------- the helper ----------
+
+def test_doi_match_is_case_and_whitespace_insensitive():
+    doi_map, title_map = dedup_maps(LIBRARY)
+    d = {"title": "totally different title", "DOI": "  10.5555/att  "}
+    assert duplicate_key(d, doi_map, title_map) == "AAAA1111"
+
+
+def test_normalized_title_match():
+    doi_map, title_map = dedup_maps(LIBRARY)
+    d = {"title": "deep residual learning revisited"}
+    assert duplicate_key(d, doi_map, title_map) == "BBBB2222"
+
+
+def test_doi_wins_when_doi_and_title_point_at_different_items():
+    doi_map, title_map = dedup_maps(LIBRARY)
+    d = {"title": "Some Other Paper", "DOI": "10.5555/ATT"}
+    assert duplicate_key(d, doi_map, title_map) == "AAAA1111"
+
+
+def test_no_match_returns_none():
+    doi_map, title_map = dedup_maps(LIBRARY)
+    d = {"title": "A Brand New Paper", "DOI": "10.9999/new.1"}
+    assert duplicate_key(d, doi_map, title_map) is None
+
+
+def test_items_without_doi_do_not_poison_the_doi_map():
+    doi_map, _ = dedup_maps(LIBRARY)
+    assert "" not in doi_map
+    assert set(doi_map) == {"10.5555/att", "10.1103/physrevlett.116.061102"}
+    # an incoming item with no DOI falls through to the title check only
+    _, title_map = dedup_maps(LIBRARY)
+    assert duplicate_key({"title": "A Brand New Paper"}, doi_map, title_map) is None
+
+
+def test_unknown_doi_still_matches_on_title():
+    doi_map, title_map = dedup_maps(LIBRARY)
+    d = {"title": "attention is all you need", "DOI": "10.9999/unseen"}
+    assert duplicate_key(d, doi_map, title_map) == "AAAA1111"
+
+
+def test_first_writer_wins_on_duplicate_library_rows():
+    doi_map, title_map = dedup_maps(_lib(("KEY00001", "T", "10.1/x"),
+                                         ("KEY00002", "T", "10.1/x")))
+    assert duplicate_key({"title": "T", "DOI": "10.1/X"}, doi_map, title_map) == "KEY00001"
+
+
+# ---------- create_items records the existing key ----------
+
+class FakeZ:
+    def __init__(self, existing):
+        self._existing = existing
+        self.created_payloads = []
+
+    def top(self):
+        return "TOP"
+
+    def everything(self, _):
+        return self._existing
+
+    def item_template(self, itemtype):
+        return {"itemType": itemtype, "title": "", "DOI": "", "tags": [],
+                "collections": []}
+
+    def create_items(self, payloads):
+        self.created_payloads.append(payloads)
+        return {"successful": {str(i): {"key": f"NEW0000{i}"}
+                               for i in range(len(payloads))}, "failed": {}}
+
+
+def _zot(existing):
+    z = Zot.__new__(Zot)
+    z.z = FakeZ(existing)
+    z.conventions = None
+    return z
+
+
+def test_create_items_records_existing_key_in_skipped_meta():
+    z = _zot(LIBRARY)
+    out = z.create_items([{"itemType": "journalArticle", "title": "Fresh One"},
+                          {"itemType": "journalArticle",
+                           "title": "attention is all you need!"}])
+    created = [r for r in out if r.get("key")]
+    skipped = [r for r in out if r.get("skipped")]
+    assert [c["title"] for c in created] == ["Fresh One"]
+    assert skipped == [{"title": "attention is all you need!",
+                        "skipped": "duplicate", "existing_key": "AAAA1111"}]
+
+
+def test_create_items_skips_on_doi_and_names_that_item():
+    z = _zot(LIBRARY)
+    out = z.create_items([{"itemType": "journalArticle", "title": "Renamed Paper",
+                           "DOI": "10.5555/ATT"}])
+    assert out == [{"title": "Renamed Paper", "skipped": "duplicate",
+                    "existing_key": "AAAA1111"}]
+    assert z.z.created_payloads == []  # nothing sent to the API
+
+
+def test_create_items_no_dedup_creates_everything():
+    z = _zot(LIBRARY)
+    out = z.create_items([{"itemType": "journalArticle",
+                           "title": "Attention Is All You Need"}], dedup=False)
+    assert len(out) == 1 and out[0]["key"] == "NEW00000"
+
+
+# ---------- the dry-run notice ----------
+
+def test_dup_notice_shape():
+    doi_map, title_map = dedup_maps(LIBRARY)
+    msg = dup_notice({"title": "Attention Is All You Need"}, doi_map, title_map)
+    assert msg == ("!! already in library as AAAA1111 — --apply will skip it "
+                   "(use --no-dedup to force)")
+
+
+def test_dup_notice_none_for_new_item():
+    doi_map, title_map = dedup_maps(LIBRARY)
+    assert dup_notice({"title": "Brand New", "DOI": "10.9/z"}, doi_map, title_map) is None
+
+
+def test_dup_notice_with_empty_maps_never_warns():
+    assert dup_notice({"title": "Attention Is All You Need"}, {}, {}) is None
+
+
+def test_dup_notice_names_the_doi_match_not_the_title_match():
+    doi_map, title_map = dedup_maps(LIBRARY)
+    msg = dup_notice({"title": "Some Other Paper", "DOI": "10.5555/att"},
+                     doi_map, title_map)
+    assert "AAAA1111" in msg and "CCCC3333" not in msg
+
+
+def test_empty_library_yields_empty_maps():
+    assert dedup_maps([]) == ({}, {})
+    assert duplicate_key({"title": "Anything"}, {}, {}) is None

zotkit-0.7.0/tests/test_enrich.py

@@ -0,0 +1,167 @@
+"""Offline tests for zotkit.enrich: the version-of-record gate in plan_enrich
+and the set_abstract guard/force/stamp matrix. No network, no live library —
+the Zotero client and CrossRef fetch are faked."""
+import types
+
+import pytest
+
+from zotkit import enrich
+from zotkit import metadata as md
+
+SSRN_ITEM = {"itemType": "journalArticle", "title": "Some Working Paper",
+             "publicationTitle": "SSRN Electronic Journal",
+             "DOI": "10.2139/ssrn.2407199", "creators": []}
+PRL_ITEM = {"itemType": "journalArticle", "title": "GW150914",
+            "publicationTitle": "Physical Review Letters",
+            "DOI": "10.1103/PhysRevLett.116.061102", "creators": []}
+
+SSRN_PREPRINT = {"itemType": "preprint", "title": "Some Working Paper",
+                 "abstractNote": "has one", "creators": [],
+                 "DOI": "10.2139/ssrn.2407199", "extra": "", "url": "",
+                 "archiveID": "", "tags": [], "collections": [],
+                 "relations": {}, "repository": "SSRN", "date": ""}
+
+
+def _read_only_zot(item_data):
+    return types.SimpleNamespace(z=types.SimpleNamespace(
+        item=lambda k: {"data": dict(item_data), "key": k, "version": 1}))
+
+
+def _plan(monkeypatch, item_data, fetched, rebuild):
+    monkeypatch.setattr(md, "fetch_doi", lambda doi: dict(fetched))
+    return enrich.plan_enrich(_read_only_zot(item_data), "KEY00001",
+                              rebuild_record=rebuild)
+
+
+# ---------- plan_enrich: version-of-record gate ----------
+
+def test_ssrn_doi_never_rebuilds(monkeypatch):
+    p = _plan(monkeypatch, SSRN_PREPRINT, SSRN_ITEM, rebuild=True)
+    assert p["rebuild"] is None
+    assert any("no version-of-record upgrade" in n and "repository DOI" in n
+               for n in p["notes"])
+
+
+def test_repository_doi_still_fills_missing(monkeypatch):
+    p = _plan(monkeypatch, SSRN_PREPRINT, dict(SSRN_ITEM, date="2024-01-15"),
+              rebuild=False)
+    assert p["fills"].get("date") == "2024-01-15"
+    assert not any("version-of-record" in n for n in p["notes"])
+
+
+def test_genuine_journal_doi_rebuilds(monkeypatch):
+    real_preprint = dict(SSRN_PREPRINT, DOI="10.1103/PhysRevLett.116.061102",
+                         repository="arXiv")
+    p = _plan(monkeypatch, real_preprint, PRL_ITEM, rebuild=True)
+    assert p["rebuild"] == "journalArticle"
+
+
+def test_layer2_guard_blocks_disguised_record(monkeypatch):
+    # non-blacklist DOI prefix, but the fetched record is the SSRN pseudo-journal
+    disguised = dict(SSRN_ITEM, DOI="10.9999/fake.1")
+    odd_preprint = dict(SSRN_PREPRINT, DOI="10.9999/fake.1")
+    p = _plan(monkeypatch, odd_preprint, disguised, rebuild=True)
+    assert p["rebuild"] is None
+    assert any("pseudo-journal" in n for n in p["notes"])
+
+
+def test_no_identifier_skips_without_fetching(monkeypatch):
+    monkeypatch.setattr(md, "fetch_doi",
+                        lambda doi: pytest.fail("must not fetch CrossRef"))
+    noid = dict(SSRN_PREPRINT, DOI="")
+    p = enrich.plan_enrich(_read_only_zot(noid), "KEY00001",
+                           rebuild_record=False)
+    assert p["status"] == "needs-identifier"
+
+
+# ---------- set_abstract: guard / force / stamp matrix ----------
+
+class FakeZ:
+    def __init__(self, data):
+        self._data = data
+        self.updated = None
+
+    def item(self, key):
+        return {"key": key, "version": 7, "data": dict(self._data)}
+
+    def update_item(self, item):
+        self.updated = item
+
+
+def zot_with(data):
+    return types.SimpleNamespace(z=FakeZ(data))
+
+
+BASE = {"itemType": "journalArticle", "title": "T", "abstractNote": "",
+        "extra": "", "key": "K1", "version": 7}
+
+
+def test_fresh_item_writes_cleaned_abstract_and_stamp():
+    z = zot_with(BASE)
+    r = enrich.set_abstract(z, "K1", "some text\nwrapped", "cnki")
+    d = z.z.updated["data"]
+    assert d["abstractNote"] == "some text wrapped"  # unwrap applied to paste
+    assert d["extra"] == "abstract-source: cnki"
+    assert r["replaced"] is False
+
+
+def test_existing_abstract_refused_without_force():
+    z = zot_with(dict(BASE, abstractNote="old text"))
+    with pytest.raises(md.MetadataError, match="--force"):
+        enrich.set_abstract(z, "K1", "new", "manual")
+    assert z.z.updated is None  # nothing written
+
+
+def test_stale_stamp_alone_refused_without_force():
+    z = zot_with(dict(BASE, extra="abstract-source: arxiv"))
+    with pytest.raises(md.MetadataError, match="--force"):
+        enrich.set_abstract(z, "K1", "new", "manual")
+    assert z.z.updated is None
+
+
+def test_force_replaces_abstract_and_rewrites_stamp_in_place():
+    z = zot_with(dict(BASE, abstractNote="old",
+                      extra="arXiv: 2401.00001\nabstract-source: arxiv\n"
+                            "Citation Key: x"))
+    r = enrich.set_abstract(z, "K1", "new text", "publisher", force=True)
+    d = z.z.updated["data"]
+    assert d["abstractNote"] == "new text"
+    assert d["extra"] == ("arXiv: 2401.00001\nabstract-source: publisher\n"
+                          "Citation Key: x")
+    assert d["extra"].count("abstract-source:") == 1
+    assert r["replaced"] is True
+
+
+def test_force_on_unstamped_item_appends_stamp_keeping_lines():
+    z = zot_with(dict(BASE, abstractNote="old", extra="Some: line"))
+    enrich.set_abstract(z, "K1", "new", "manual", force=True)
+    d = z.z.updated["data"]
+    assert d["extra"] == "Some: line\nabstract-source: manual"
+
+
+def test_empty_after_cleaning_errors_and_writes_nothing():
+    z = zot_with(BASE)
+    with pytest.raises(md.MetadataError, match="empty"):
+        enrich.set_abstract(z, "K1", "  \n\u00ad ", "manual")
+    assert z.z.updated is None
+
+
+def test_open_vocabulary_slug_accepted():
+    z = zot_with(BASE)
+    enrich.set_abstract(z, "K1", "x", "some-new-source2")
+    assert z.z.updated is not None
+
+
+@pytest.mark.parametrize("bad", ["CNKI", "with space", "", "-lead", "中文"])
+def test_bad_slug_refused(bad):
+    z = zot_with(BASE)
+    with pytest.raises(md.MetadataError):
+        enrich.set_abstract(z, "K1", "x", bad)
+    assert z.z.updated is None
+
+
+def test_item_type_without_abstract_field_refused():
+    z = zot_with({"itemType": "note", "extra": "", "key": "K1"})
+    with pytest.raises(md.MetadataError, match="no abstract field"):
+        enrich.set_abstract(z, "K1", "x", "manual")
+    assert z.z.updated is None