Skip to content
ZincGitHubDownload

WASM plugin API: library, search, batching, notifier

View as Markdown

Area library. WIT: plugin-api/wit/library.wit. Phase 1 is design only. “Needs core” in a status means the WIT is written but Zinc’s core (core/src/, core/schema.sql) does not serve the feature yet; that is fine for phase 1.

Sources read: Zotero chrome/content/zotero/xpcom/data/*.js (items, collections, searches, tags, relations, libraries, groups, notes, itemFields, cachedTypes, creators, feeds), search conditions (data/searchConditions.js, 59 conditions), attachments.js, fulltext.js, cite.js, quickCopy.js, duplicates.js, notifier.js, db.js, translation/translators.js; Zinc’s core/schema.sql, core/src/api-types.ts, docs/developer-guide/http-api.md, database.md, and the earlier compat layer (gpui-ui/src/plugins/zotero/). Zotero.Translate itself and Zotero.Utilities.Item live in git submodules that the sparse checkout does not contain; their rows come from Zotero’s public API, not from the checked-out source.

Interfaces in library.wit

Interface Direction What
library import libraries, items (query, get), collections, tags, relations, saved searches, duplicates, trash, apply (atomic batch)
attachments import attachment info, file bytes, import / link / replace / rename, Find Full Text, reader view state
fulltext import indexed text, index state, set content, search
schema import item types, fields, creator types
cite import styles, bibliography / citation formatting, Quick Copy
translate import list / run import, export, lookup, web translators
sync-control import sync state, start a sync
data-utils import dates, CSL JSON, note title, display title, extra parsing, identifier extraction
notifier import subscribe, unsubscribe, trigger, and the event types
notifier-handler export the plugin implements on-events(subscription, batch)

world.wit (lifecycle) must import library, attachments, fulltext, schema, cite, translate, sync-control, data-utils, notifier and export notifier-handler. The world needs the export and the import to be different interfaces because a world cannot export and import the same interface name; that is why the callback is not inside notifier.

Types come from types.wit: item-key, collection-key, search-key, library-id, json, error, plugin-id, epoch-ms. No local error type was needed.

1. Parity table

Status: covered, partial (what is missing is stated), not planned (why, and what to do instead).

Items and item objects (data/items.js, data/item.js, data/dataObjects.js, data/dataObject.js)

Zotero capability Zinc WIT Status
Zotero.Items.get/getAsync/getByLibraryAndKey(Async) (dataObjects.js) library.get-items(keys, get-options) returns item JSON covered. Numeric itemID is not exposed: Zinc has none; keys are unique across libraries
Zotero.Items.getAll, getAllIDs/Keys, getDeleted library.query-items, query-keys, scope all / trash covered
Item.getField/setField/getFields, getCreators/setCreators/getCreator*, getTags, getCollections, getRelations, getNote, getAttachments fields of item JSON from get-items; changes through apply.update-item covered. A plugin edits JSON, not an object with setters
Item.toJSON, Item.fromJSON, toResponseJSON (item.js) item JSON is the Web API data object covered (see design note on version and dateModified)
Item.saveTx, item.save() inside executeTransaction (dataObject.js) library.apply with create-item / update-item covered
Item.hasChanged, Item.diff, multiDiff item-update.expected-modified for conflict detection; diff is guest-side on JSON partial: no diff helper
Item.clone, Zotero.Items.copyChildItems create-item with JSON copied by the plugin; duplicate exists in the core (POST /api/items/:key/duplicate) but has no WIT call partial: add duplicate-item if wanted (open question 4)
Item.moveToLibrary, Zotero.Items.moveChildItems, Attachments.moveAttachmentToLibrary/copyAttachmentToLibrary create-item with library, then trash-items partial. A real move keeps keys; Zinc keys must stay globally unique, so a move is a copy plus trash. Needs core for files
Item.isRegularItem/isNote/isAttachment/isTopLevelItem/isInTrash/isAnnotation, topLevelItem, Zotero.Items.getTopLevel/keepTopLevel/keepParents itemType, parentItem, deleted in JSON; item-summary.parent-key, in-trash covered, guest-side helpers
Item.numChildren/numNotes/numAttachments/numAnnotations item-summary.attachment-count, note-count; get-children covered (annotation count: see reader)
Item.getDisplayTitle, getTabTitle data-utils.display-title covered (tab title is UI)
Item.getNoteTitle, Zotero.Notes.noteToTitle data-utils.note-to-title covered
Item.setNote, note HTML note field of item JSON in apply covered
Zotero.Items.getFirstCreatorFromJSON/FromData, getSortTitle data-utils.first-creator, sort-title covered
Item.addRelatedItem/removeRelatedItem, getRelations, addRelation, removeRelation, setRelations apply.add-related / remove-related; relations in item JSON covered for items. Zinc’s core only knows dc:relation as a UI concept but stores relations JSON verbatim
Zotero.Relations.getByPredicateAndObject/getByObject (relations.js) library.find-by-relation partial. Needs core: no relation index (JSON in items.data)
Item.getLinkedItem/addLinkedItem, Collection.getLinkedCollection relations (owl:sameAs) in JSON; find-by-relation partial: no direct helper, same core gap
Zotero.Items.addToPublications/removeFromPublications, Item.setPublications apply.add-to-publications, remove-from-publications; scope publications partial. Core lists publications (publications=1) but has no write route
Item.getExtraField, Zotero.Utilities.Internal.extractExtraFields data-utils.parse-extra covered
Item.getUsedFields, getFieldsNotInType, setType JSON edit and schema.get-schema covered (type change by update-item with new itemType; core must drop invalid fields: needs core check)
Item.getImageSrc, getItemTypeIconName UI not planned here: icons belong to the ui area
Item.migrateExtraFields, updateCreatedByUser internal migration not planned: Zotero upgrade code, not a plugin API
Zotero.Items.getLastRead/getLastReadAttachmentIDs/clearAllLastRead, Item.getItemLastRead attachment-info.last-read partial. Needs core: no lastRead column
Zotero.Items.findMissingLinkedFiles, numDistinctFileAttachmentsForLabel query-items plus attachments.get-info (file-exists) partial: no single call
Zotero.Items.merge, Zotero.Duplicates.findAll/find/findAllInSet, getSearchObject library.merge-items, find-duplicates covered
Zotero.Duplicates “not a duplicate” marks library.mark-not-duplicates covered
Zotero.Items.trash/trashTx, Item.deleted = true apply.trash-items covered
Item.deleted = false (restore), Zotero.Items.undoTrash apply.restore-items covered
Item.erase/eraseTx, Zotero.Items.erase apply.erase-items (must be trashed first) covered
Zotero.Items.emptyTrash, purge library.empty-trash covered. purge (orphan value cleanup) is internal
Zotero.Items.hasDeleted, trash listing query-items with scope trash covered
item.version, synced, dateModified handling, skipDateModifiedUpdate version and dateModified in JSON; host stamps dateModified on every change partial: no skipDateModifiedUpdate; a plugin cannot back-date (by design, see notes)
Item types used by plugins: annotation items (getAnnotations, isAnnotation, Zotero.Items.get(annotationID)) none in this area partial: annotations are reader data in Zinc (annotations table). reader.wit’s annotations interface is the only route (typed, batched, with the same field names); get-items, query-items and apply answer invalid-argument for an annotation key

Collections (data/collections.js, data/collection.js)

Zotero capability Zinc WIT Status
Zotero.Collections.getByLibrary/getByParent/get library.list-collections covered
Collection.getChildCollections/getDescendents, hasChildCollections list-collections (parent) covered, guest-side
Collection.getChildItems/hasChildItems/hasItem/hasDescendent library.get-collection-items(key, recursive); scope collection covered
Collection.name = / parentID = / saveTx apply.create-collection, update-collection covered
Collection.addItem(s)/removeItem(s) apply.add-to-collection, remove-from-collection covered
Collection.erase / eraseTx, deleteItems apply.erase-collection(trash-items) covered
Collection.trash, collections in the trash (Zotero 7), Zotero.Collections deleted flag none partial: Zinc deletes collections for good (core/schema.sql has no deleted flag). Needs core
Collection.toJSON/fromJSON, serialize collection-info covered (record, not JSON)
Zotero.Collections.getRecent/addToRecent, registerChildCollection UI state not planned: UI cache and recent-list for the collection picker
Collection relations relations not on collection-info partial. Needs core: collections have no relations column
Collection.version, sync fields collection-info.version covered

Tags (data/tags.js)

Zotero capability Zinc WIT Status
Zotero.Tags.getAll/getAllWithin/getTagItems library.list-tags(library, within); query-items with tags covered
Item.addTag/removeTag/setTags/hasTag/replaceTag/removeAllTags, tag type apply.add-tags, remove-tags, update-item.patch.tags; tag-kind covered
Zotero.Tags.rename library.rename-tag covered
Zotero.Tags.removeFromLibrary, removeAutomaticFromLibrary, purge library.delete-tags, delete-automatic-tags covered
Zotero.Tags.getColor/getColors/setColor/getColorByPosition, toggleItemsListTags library.get-tag-colors, set-tag-colors partial: colour list only. Emoji tags and emojiTag flags are UI display, left to ui
Zotero.Tags.extractEmojiForItemsList, compareTagsOrder, equals, cleanData n/a not planned: display and string helpers; the plugin can reimplement

Saved searches and searching (data/search.js, searches.js, searchConditions.js, quicksearch)

Zotero capability Zinc WIT Status
Zotero.Search.addCondition(name, operator, value, required), getConditions, setScope, fromJSON/toJSON search-definition / search-condition partial. The record carries any of Zotero’s 59 condition names, but the core compiler (core/src/searches/compile.ts) supports a subset (title, creator, year, date fields, publicationTitle, itemType, tag, collection, note, attachmentFileType, fulltextContent, anyField, schema fields; no groupStart/groupEnd, numberfield, lastRead, annotation*, retracted, tempTable). Needs core
Zotero.Search.search() (item ids), getSQL library.query-items / query-keys with search covered for supported conditions; getSQL is not planned (no SQL). Zotero 10 added condition groups and removed fulltextWord (use fulltextContent) and migrated childNote to note; Zinc accepts fulltextContent and note, and has no group conditions yet (see the first row)
joinMode any/all, includeParentsAndChildren, recursive, noChildren, includeDeleted, required search-options, search-condition.required covered
Zotero.Search.setScope(search) (search within search) item-query.scope = saved-search plus search partial: nesting one saved search in another via a savedSearch condition is not in the core
Zotero.SearchConditions.getStandardConditions/getLocalizedName library.list-search-conditions covered
Zotero.Searches.getAll/getByLibrary/get, getNextName library.list-saved-searches, get-saved-search covered. Zotero 10 lets several saved searches and collections be selected at once (getSelectedSavedSearches, getSelectedCollections); a Zinc plugin gets lists from extend.context and runs one item-query per scope (zotero-versions.md)
Search.name = / saveTx / erase apply.create-saved-search, update-saved-search, erase-saved-search covered
Quick search modes (quicksearch-titleCreatorYear/fields/everything, Zotero.Search quick) item-query.text with text-mode covered
Zotero.Search.hasPostSearchFilter, tempTable condition n/a not planned: internal SQL planner
Search results with resultLevel, fulltextContent item-query.search, fulltext.search partial: resultLevel is not in the core
Aggregates (SELECT ... GROUP BY) written by plugins in SQL library.facets partial: one grouping field per call, listed fields only

Libraries and groups (data/libraries.js, library.js, groups.js)

Zotero capability Zinc WIT Status
Zotero.Libraries.getAll/get/exists/getName/getType, isEditable, isFilesEditable, hasTrash library.list-libraries → library-info covered
Zotero.Groups.getAll/get/getByLibraryID, getGroupIDFromLibraryID, getPermissionsFromJSON library-info.group-id, editable, files-editable covered
Zotero.Libraries.getVersion/setVersion/getLastSyncTime, Library.updateLastSyncTime, incrementClientVersion n/a not planned: sync internals. Use sync-control.get-state
Library.hasItems/hasCollections/hasSearches, waitForDataLoad, getDataLoaded n/a not planned: Zinc has no lazy data loading phases; calls always see the data
Library.saveTx/eraseTx, Zotero.Groups.register (create/delete libraries) n/a not planned: libraries are created by sync from zotero.org, not by plugins
Zotero.Libraries.userLibraryID, Zotero.Groups selected library library-id 1 covered

Schema and types (data/itemFields.js, cachedTypes.js, creators.js)

Zotero capability Zinc WIT Status
Zotero.ItemTypes.getAll/getName/getID/getTypesForItemType, getLocalizedString schema.get-schema partial: English labels only. Localized labels need the host’s l10n (lifecycle)
Zotero.ItemFields.getAll/getName/getItemTypeFields/getBaseMappedFields/isValidForType/isBaseField, isDate/isLong/isMultiline/isAutocompleteField schema.field-info (base-field, is-date, is-long, is-multiline) partial. Needs core: /api/schema has no is-* flags; the host can hardcode them. Autocomplete flag omitted
Zotero.CreatorTypes.getTypesForItemType/getPrimaryIDForType, isValidForItemType schema.creator-type-info covered
Zotero.ItemTypes.add, custom types and fields (isCustom) n/a not planned: Zinc follows Zotero’s schema. A plugin stores its own data in extra, relations or its private storage (lifecycle)
Zotero.Creators.get/getIDFromData/getItemsWithCreator/countItemAssociations/updateCreator, Creators.cleanData n/a not planned: Zinc stores creators inside item JSON, with no creator table. Rename a creator across items with query-items (condition creator) plus apply.update-item
Zotero.DataObjectUtilities, Zotero.CollectionTreeRow n/a not planned: Zotero UI internals

Attachments (attachments.js, item.js attachment methods)

Zotero capability Zinc WIT Status
Item.getAttachmentLinkMode/MIMEType/Charset, isPDFAttachment, isFileAttachment, isLinkedFileAttachment, isImportedAttachment, isSnapshotAttachment, isEPUBAttachment, getFilename, fileExists, getAttachmentLastPageIndex attachments.get-info → attachment-info partial: charset and last-read need core
Item.getFilePath/getFilePathAsync/getFile attachment-info.path (permission library.files.paths) covered, permission-gated
Attachments.getStorageDirectory(ByID/ByLibraryAndKey), createDirectoryForItem, createTemporaryStorageDirectory, fixPathSlashes, getBaseDirectoryRelativePath, resolveRelativePath n/a not planned: a plugin has no file system. Ask the host to read, write, import or rename instead
Attachments.hasMultipleFiles/getNumFiles/getTotalFileSize attachments.storage-of covered
Attachments.importFromFile attachments.import-bytes, file-writer covered. A plugin passes bytes, not a path
Attachments.linkFromFile, linkFromFileWithRelativePath attachments.link-file covered (path permission)
Attachments.importFromURL, downloadFile, importSnapshotFromFile attachments.import-from-url covered. Network permission applies
Attachments.linkFromURL attachments.link-url covered
Attachments.importFromDocument, linkFromDocument, importFromSnapshotContent, importEmbeddedImage, copyEmbeddedImage import-bytes with HTML bytes partial: no DOM document; embedded note images have no WIT call and the core does not store them separately. Needs core
Attachments.importFromNetworkStream, createURLAttachmentFromTemporaryStorageDirectory n/a not planned: Firefox network stream internals
Item.renameAttachmentFile, Attachments.getFileBaseNameFromItem, getAttachmentRenameTemplate, shouldAutoRenameFile, isAutoRenameFilesEnabledForLibrary, rename setting attachments.rename-file, rename-by-template partial: template read and auto-rename settings are prefs; the prefs interface (lifecycle) should expose them
Item.relinkAttachmentFile, deleteAttachmentFile attachments.relink-file, delete-file covered
Attachments.convertLinkedFileToStoredFile read-file + import-bytes + trash partial: no single call. Needs core
Item.getBestAttachment(s), getBestAttachmentState attachments.best-attachment, best-attachments; item-summary.best-attachment covered
Attachments.getFileResolvers/getPDFResolvers, addAvailableFile(s), addAvailablePDF(s), canFindFileForItem, downloadFirstAvailableFile, addFileFromURLs attachments.find-available-files, get-find-job, cancel-find-job partial: Zinc has one fixed resolver chain (Unpaywall, Europe PMC, institution). A plugin cannot add a resolver
Attachment file write by plugin (OS.File.writeAtomic on the storage path, used by PDF tools) attachments.replace-file covered
Zotero.launchFile, ZoteroPane.showAttachmentInFilesystem attachments.open-file-external, reveal-file covered
Attachments.isPDFJSDocument/isPDFJSBrowser, linkModeToName/FromName link-mode enum covered
Item.setAttachmentLastPageIndex, reader view state file attachments.get-view-state, set-view-state covered (the stored copy of the JSON that reader.reader-state.primary-view-state holds while a reader is open; the reader owns the format)

Full text (fulltext.js)

Zotero capability Zinc WIT Status
Zotero.Fulltext.getIndexedState/isFullyIndexed/getPages, getIndexStats fulltext.get-index-state partial: no page counts, no stats. Needs core
Read .zotero-ft-cache / indexed content fulltext.get-content covered
Fulltext.setItemContent, custom indexing by plugins fulltext.set-content partial. Needs core: fulltext.source accepts only zotero-cache and document-worker; add plugin
Fulltext.indexItems, indexDocument/indexPDF/indexEPUB, rebuildIndex, reindexTruncated, queueItem fulltext.reindex partial. Needs core: no reindex route
Fulltext.findItemsWithContent, findTextInItems, getContentSearchSQL fulltext.search; fulltextContent search condition partial: FTS5 (stemmed) rather than Zotero’s word index; results differ. Since Zotero 10 Zotero also uses FTS5 (an attached ftindex database, fulltextWords tables dropped, fulltextWord condition removed, fulltextContent kept), so word-index SQL in a ported plugin has no equivalent in either: use fulltext.search
Fulltext.getAttachmentIndexQueueCount, processAttachmentIndexQueue, etc. fulltext.get-queue-status partial: counts only
Fulltext.canIndex, getItemCacheFile, semanticSplitter, converter paths, sync content (getUnsyncedContent, processSyncedContent, registerSyncContentProcessor), clearItemWords, vacuum, optimizeContentIndex n/a not planned: Zotero’s own index internals and its full-text sync. Zinc uses SQLite FTS5

Raw database (db.js)

Zotero capability Zinc WIT Status
Zotero.DB.queryAsync/valueQueryAsync/rowQueryAsync/columnQueryAsync/queryTx (read) library.query-items, query-keys, count-items, facets, list-tags not planned for raw SQL; see design note 3. Common read cases covered by the query interface
Zotero.DB.queryAsync writes (UPDATE/INSERT/DELETE), executeSQLFile library.apply not planned for raw SQL writes. Writing around the data layer breaks the sync outbox triggers, the FTS and quick-search indexes and migrations
Zotero.DB.executeTransaction, inTransaction, requireTransaction, waitForTransaction, Zotero.DB.transactionTimestamp library.apply (one atomic batch) covered. No interactive transactions: a transaction cannot span calls, so one cannot hold the write lock across a process boundary
Zotero.DB.tableExists/columnExists/indexExists/getColumns, vacuum, backupDatabase, integrityCheck, addCallback, observe, loadExtension, corruption handlers, closeDatabase n/a not planned: Zotero schema and storage engine specifics
Zotero.DataDirectory paths for the database n/a not planned: a plugin must not name library files; also unsafe

Notifier (notifier.js)

Zotero capability Zinc WIT Status
Zotero.Notifier.registerObserver(ref, types, id, priority) notifier.subscribe(subscription) + export notifier-handler.on-events partial. Needs core: no change feed. Today only this layer’s own writes are seen (see notes). Decided 2026-11-18: the core gets a change log in phase 2
ref.notify(event, type, ids, extraData) event record: object, kind, ids, extra covered
unregisterObserver(id) notifier.unsubscribe covered
Types: collection, search, item, file, collection-item, item-tag, tag, group, trash, relation, setting, sync, share, share-items, bucket, api-key, feed, feedItem object-type enum covered as names. Events fire only for data Zinc has: no share, share-items, bucket, api-key, feed, feed-item events (no such features): partial
UI types tab, itemtree, itempane, infobox none in object-type. Tab changes (with selection, view and theme changes) arrive once, from extend.subscribe-events; the other three are internal refresh signals partial: tab events are in extend; itemtree, itempane, infobox are not planned
Events add, modify, delete, move, remove, refresh, redraw, trash, restore, index event-kind covered. unreadCountUpdated, pageChange (file) and open (file) belong to feeds / reader: not planned for feeds, reader area for the rest
Transaction merging, Notifier.begin/commit/queue, skipNotifier, skipSelect, skipAutoSync batches merge per apply / flush; apply-options.skip-notify; event.options partial: skipSelect is UI; plugins cannot open notifier transactions (begin/commit not planned)
Priority ordering of observers subscription.priority covered
Notifier.trigger by plugins (custom events) notifier.trigger for other and UI types only partial: by design a plugin cannot forge item events
Notifier.getLeakedObserverIDs n/a not planned: window leak debugging

Cite, Quick Copy, Translate, Sync, utilities

Zotero capability Zinc WIT Status
Zotero.Styles.getAll/getVisible/get, Zotero.Style.getXML cite.list-styles, get-style-xml covered
Zotero.Styles.install, Style.remove cite.install-style, remove-style partial: install by repository id only; no install from XML text (core installs from zotero.org; add install-style-xml)
Zotero.Cite.makeFormattedBibliographyOrCitationList, Zotero.QuickCopy.getFormattedNameFromSetting, Style.getCiteProc() cite.format partial: output html / text / rtf / note citation markup (note-citation, for note-editor.insert-html), locator, prefix, suffix, suppress-author supported; a plugin cannot get the citeproc engine object, nor use footnote or integration callbacks
Zotero.QuickCopy.getContentFromItems, getNoteFormat, getFormatFromURL, annotationsToNote, site settings cite.quick-copy, get-quick-copy-settings partial: no per-site format rules, no export-translator Quick Copy format, no annotation to note. Needs core
Zotero.Cite.System (retrieveItem, getAbbreviation), Zotero.Cite.getLocatorString n/a not planned: citeproc engine glue. Plugin can ship its own citeproc and feed it CSL JSON from data-utils.item-to-csl-json
Zotero.Translators.getAllForType/get/getWebTranslatorsForLocation/getImportTranslatorsForLocation translate.list-translators partial: the web translators-for-URL matching is not exposed
Zotero.Translators.save/load/loadFromFile (install a translator) n/a not planned in phase 1: arbitrary translator JS would run in the core’s translator sandbox, outside the plugin sandbox. Open question 5
Zotero.Translate.Import (setString, setTranslator, translate) translate.import-text covered
Zotero.Translate.Export translate.export-items covered (text output only; binary output formats are not returned: partial)
Zotero.Translate.Search (lookup by identifier) translate.lookup covered for DOI, PMID, PMCID, arXiv, ISBN (what Zinc’s lookup resolves); other search translators: partial
Zotero.Translate.Web, HiddenBrowser, Zotero.Translate.ItemSaver, translator callbacks (setHandler, select) translate.web, web-select partial: choose-then-select flow only. No DOM Document hand-over, no custom item saver or handlers
Zotero.Sync.Runner.sync(), Runner.running, Sync.Runner.addListener sync-control.sync-now, get-state; notifier type sync covered
Zotero.Sync.Data, Sync.Storage, Sync.Server, Zotero.SyncedSettings n/a not planned: sync engine internals. Plugin data syncs through item JSON relations or extra, or not at all
Zotero.Date.strToDate, strToISO, sqlToDate, dateToSQL, multipartToStr, getLocaleDateOrder data-utils.parse-date, to-iso-date, display-date partial: the three common ones; SQL date helpers are pure and a plugin can use its own date library. Locale date order: ui/lifecycle l10n
Zotero.Utilities.Item.itemToCSLJSON, itemFromCSLJSON data-utils.item-to-csl-json, item-from-csl-json covered (item-from-csl-json needs core: no CSL to item mapper outside import)
Zotero.Utilities.extractIdentifiers, cleanDOI, cleanISBN, isDOI data-utils.extract-identifiers covered for extraction. Cleaning is guest-side
Zotero.Utilities string, HTML and XML helpers (trim, cleanTags, capitalizeTitle, xpath, parseURL) n/a not planned: generic code; ship it in the plugin
Feeds: Zotero.Feeds, FeedItems, Feed, FeedReader n/a not planned: Zinc has no RSS feeds feature. A plugin can fetch a feed with the lifecycle’s network permission and create items with apply
Zotero.Retractions, Zotero.Report, Zotero.Timeline n/a not planned: retraction checks and reports are features of Zotero itself; plugins read the retracted search condition when it exists (needs core)

Counts (rows in the tables above, counted by script): covered 69, partial 39, not planned 25.

2. Design notes

  1. One write call, library.apply. Zotero writes with item.saveTx(), Zotero.DB.executeTransaction(async () => {...}) and many small awaits. Each await would be a process crossing, and an interactive transaction (read, decide, write while holding the lock) would let a stuck plugin hold the library write lock. Instead a plugin sends a list of changes and the core runs them in one SQLite transaction in order, all or nothing, and answers with the new keys. new-keys lets a plugin link objects it creates in the same batch (parent and child, collection and member) without a round trip. Conflicts use optimistic concurrency (expected-modified) in place of hasChanged. Failure reports the change index.
  2. Items are JSON, lists are cheap. Item data travels as Zotero Web API item JSON because the core stores it that way (items.data) and every guest language has a JSON parser; the open-ended field set needs no WIT change when Zotero adds fields. Lists use item-summary records with opt-in fields and expand flags, so item tables do not cost a call per row. get-items takes many keys, and get-summaries(keys, fields, expand) returns the cheap summary form with a field list for many keys (the call the extend area’s custom columns, menu contexts and row styles use after they receive item keys). There is no object with setters and no handle, so there is nothing to keep alive across the boundary and nothing to leak.
  3. Raw SQL: not planned. Reasons: Zinc’s tables are not Zotero’s (no itemData, itemDataValues, itemAttachments; items are JSON); core/schema.sql changes through migrations that plugins would break; writes would bypass the sync outbox triggers and the FTS5 and quick-search indexes; reading data JSON in SQL ties plugins to storage details. What covers the common plugin SQL: finding items by field value or date (query-items with conditions); counts by tag, type, year, creator (facets, list-tags); membership (get-collection-items); full-text hits (fulltext.search); relations (find-by-relation). Open question 1 proposes a read-only view schema for later.
  4. Notifier delivery. subscribe is a host import; delivery is the exported on-events(subscription, batch). The host coalesces events (default 50 ms window, max 1 s) and merges ids per (object, kind) as Zotero does when it commits a transaction, so a 5,000-item import is a few calls, not 5,000. One batch is in flight per subscription; the queue is bounded (256), and overflow turns into a refresh event so a plugin re-reads instead of trusting a stream with holes. origin is new and lets a plugin ignore its own writes; Zotero code uses ad-hoc flags for that. on-events returns nothing, so the host never waits on plugin code and a slow plugin only slows itself. A plugin that needs a full rescan after downtime uses refresh plus its own stored “last seen” marker (storage is a lifecycle matter).
  5. What the notifier sees today. The old compat layer saw only changes made through itself and the UI. The core has a sync_outbox fed by triggers, but those are suppressed while sync applies remote changes and rows are de-duplicated, so they are not a change feed. Phase 2 needs a core change log: a table fed by unsuppressed triggers with seq, object type, key, kind, origin and library, plus an HTTP or in-process stream. SQLite data_version (already used by /api/ui/selection) can detect changes by other processes and produce a refresh.
  6. Permissions. Declared in the manifest, enforced per call; the proposed ids are library.read, library.write, library.trash (move to trash, restore), library.erase (permanent delete, empty trash, delete a collection or saved search), library.files.read (file bytes), library.files.write (import, replace, rename, delete files, Find Full Text), library.files.paths (see or give absolute paths; also needed for link-file and relink-file), library.files.open (reveal, open externally), library.fulltext.read, library.fulltext.write, library.cite, library.cite.styles, library.translate, library.sync. import-from-url and translate.web need the lifecycle network permission for the target host. A plugin gets no notifier event for objects it could not read. The default install prompt should group them: read-only, edit library, files, dangerous (erase).
  7. File access without a file system. Bytes cross the boundary, not paths. Reads are chunked (8 MiB per call, 64 MiB whole-file cap), writes take bytes up to 64 MiB or stream through the file-writer resource, the one resource here, because a partly written upload needs a handle with a lifetime. Absolute paths are hidden unless library.files.paths is granted, since paths contain the user’s name and a plugin could otherwise recover it.
  8. Rust and JS ergonomics. Plain records, variants and lists; no callbacks except on-events. option<option<collection-key>> in collection-update.parent is the one awkward type; it gives “unchanged” versus “move to top level” and could become a variant in a later revision. Names avoid WIT keywords (include, from, import, export, type were renamed: expand, old-name, importer, exporter, object).
  9. Keys, not IDs. Zotero plugins use numeric itemID. Zinc has no numeric item id, and keys are unique across libraries. Plugin code written for Zotero that stores itemID must store keys.
  10. No object model for search. Zotero.Search is a stateful builder. Here a search is a search-definition value, used inline in item-query or saved with create-saved-search. The condition name set is Zotero’s, so documented plugin searches port; the host answers invalid-argument for conditions it cannot compile.

3. Open questions for the user

  1. Offer a read-only SQL interface later over a stable view schema (items, fields, creators, tags, collections), for plugins that need ad-hoc analytics? It would be versioned and independent of the real tables. Phase 1 says no.
  2. Should permissions be scoped to a library (My Library only, or chosen groups), or to a collection? The WIT takes library arguments everywhere, so the host can enforce either.
  3. Should erase (permanent delete) be allowed to plugins at all, or only trash? Zotero plugins can erase. Proposal: allowed behind library.erase with a visible prompt.
  4. Add duplicate-item, move-item-to-library, and convert-to-stored-file as first-class change variants? They exist in Zotero and the core has duplicate already.
  5. Translators: run a plugin-supplied translator (JS) in the core’s translator sandbox, or only existing ones? The second is what the WIT offers.
  6. Cap values (query page 1000, file read 8 MiB, upload 64 MiB, event queue 256) are guesses; confirm.
  7. Should plugin writes mark dateModified as a plugin change in a way the sync layer can show to the user (an audit trail of what each plugin changed)?

4. Needs from other areas

Resolved in the reconcile of 2026-11-18 (see README): world.wit imports and exports every interface of this file; types.wit has item-ref and the one color; the permission ids of design note 6 are in the manifest schema; the notifier no longer has tab, itemtree, itempane, infobox; the view state JSON has one owner (reader), with attachments.get-view-state as its stored copy; get-summaries was added for extend; cite.format has the note-citation output for reader; annotation items go through annotations only; fulltext.get-content (whole document, indexed) and reader.get-page-text (pages of an open reader) both stay.

Still open:

  • lifecycle (prefs): the attachment rename template, auto-rename setting and Quick Copy settings are Zotero prefs; prefs.get-app should let a plugin read them (extensions.zotero.autoRenameFiles, export.quickCopy.setting). Part of the app prefs allowlist question.
  • reader: file-open events (Zotero’s file notifier type, open, pageChange) come from reader.subscribe (opened, page-changed), not from the notifier. Relations on annotations (reader.md row 81) are not served by library.find-by-relation: open, needs a decision with the reader area.
  • ui: item and collection icons, emoji tags, and “select this item” (ZoteroPane.selectItem) are extend.select-items; item and collection icons and emoji tags have no call yet. Open.
  • Core features missing (phase 2): change log and event stream; atomic batch route (POST /api/batch); relation index and collection relations; collection trash; lastRead; charset and source = plugin for full text; reindex route; search compiler coverage (groups, number fields, lastRead, annotation conditions, retracted); schema flags; publications write; item duplicate and library move in the batch.