Skip to content

feat(sources): checked, credited and undoable Library writes - #823

Open
yaacovcorcos wants to merge 1 commit into
mainfrom
claude/sources-agent-trust-20261110
Open

yaacovcorcos wants to merge 1 commit into
mainfrom
claude/sources-agent-trust-20261110

Conversation

@yaacovcorcos

@yaacovcorcos yaacovcorcos commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

Platforms: built, gated and visually reviewed on macOS (Apple Silicon). GitHub CI ran the Linux test shards and the Windows Overleaf and packaging jobs, all passing. No Sources feature was used by hand on Windows or Linux, and Intel Mac was not run. Paths go through Node path and no native dependency or shell-out was added. Untested on Windows: the managed-bibliography file publication (link, rename and exchange paths, plus a copy fallback that leaves a partial target if it fails part way).

Before merging: the agent-context-budget check needs the agent-context-increase label (agent tool list +22,762 bytes; see below).

Problem

Library (Sources) writes could not be trusted or undone.

  • An agent could add a source with an invented or wrong DOI. Scient stored it as given, marked it "pending review", and the same agent could approve it with scient_sources_review, so the review protected nothing. Agent edits were recorded as the user's.
  • Removing a source deleted its record and PDFs at once, with no undo, and an edit could not be taken back.
  • One damaged record file broke the whole list; history grew without limit; a PDF's file creation date was stored as its publication date; registry requests carried no contact address; nothing told the user that a paper had been retracted.
  • Closing a finished import summary did nothing.

Resulting behavior

Checked writes (Phase 1, PR 1).

  • An agent's DOI is resolved at doi.org (CSL-JSON, covering Crossref, DataCite and mEDRA) and a PMID through PubMed esummary on the shared NCBI lane. identifier-not-found and identifier-mismatch (registry title differs from the agent's) write nothing; a confirmed identifier makes the registry's citation fields authoritative and stores verified; an unreachable registry adds the source as given with unchecked; no identifier is unverified. The same add path serves a person adding by identifier (actor user).
  • The review gate is gone: no pending state, no scient_sources_review tool, route or buttons. Older pending records still decode.
  • Every revision records updatedBy (user or agent); changed fields get agent provenance.

Undo (Phase 1, PR 2).

  • Trash. Removing a source moves the whole record, with its PDF references, to .scient/sources/trash/; its PDFs stay. The UI removes straight away and offers Undo in the toast (the confirmation popover is gone); Trash in the Library header's ⋯ menu restores sources or empties the trash. Restore writes a new revision credited to whoever restored it and refuses over a live source with the same ID or identifier. Emptying deletes trashed sources, their history and only PDFs that no live or trashed record refers to, and deletes no file while any record cannot be read. Detaching a PDF also keeps the file until the trash is emptied.
  • History and revert. Any kept revision can be made current again as a new revision (History in the source actions). The source keeps its ID, import date, origin and citation key; a PDF already deleted by emptying the trash is left out and counted. History is capped at 50 revisions per source, always keeping the first.
  • Agents can do the same: scient_sources_restore, scient_sources_revert, scient_sources_list with inTrash, scient_sources_remove with permanent for a trashed source, and kept revisions (who saved each, which fields changed) in scient_sources_get.

Robustness and registry data.

  • A record file that is not valid JSON, does not decode, belongs to another project or does not match its file name is skipped and reported by project path; the Library shows one quiet line naming it.
  • Local PDF import takes the publication date only from XMP prism:coverDate / prism:publicationDate, never the file's CreationDate or dc:date.
  • Contact email. Settings ▸ Documents ▸ Library holds an optional contact email (empty by default). When set, requests to api.crossref.org and api.openalex.org, including redirect hops from doi.org, carry it as mailto and in a versioned, descriptive User-Agent; no other host receives it. Other adapters read the same value.
  • Retractions and corrections. A found DOI records editorialStatus from Crossref's updated-by notices in the same doi.org response (publisher updates and Retraction Watch); a PMID from PubMed's Retracted Publication type. The most serious notice sets the state (retracted, withdrawn, expression of concern, corrected, or none). The source shows one quiet line with a link to the notice and the Library row names it; scient_sources_add and scient_sources_list report it.
  • Re-checks. scient_sources_check and every metadata refresh re-resolve a source's identifier without touching its metadata: verified with fresh editorial status, unverified with a not-found or mismatch problem (shown as "Not found in registry" / "Identifier names another work"), or unchecked when the registry is unreachable (an earlier verdict for the same identifier stays). A check that changes nothing writes no revision. Editing identifiers clears both verdicts.
  • The import summary's close button now dismisses it. reviewRequired is no longer sent for source imports, and the review tool's work-log name is replaced by names for the new tools.

All new record fields are optional; existing .scient/sources data decodes unchanged and formatVersion stays 1.

Also in this branch. Following the overnight Sources roadmap work plan, this PR also carries the Phase 2–5 streams. It is one commit on main ef51507463 with the tree of claude/sources-combined-20261110 at f3828bc76c plus that branch's Accounts seam-map entry for sourcesPermissions.ts (a6d25eabba): the stream merges failed the upstream-provenance check, so the history was squashed. The full history, with each stream's commits and merges, stays on that branch. Each was reviewed by Codex until clean; reviews and responses are in the plan folder (reviews/sources-roadmap-20261110/reviews/).

  • Cite (S2): citation keys (kept from imports, generated otherwise, frozen once used, rename updates documents), [@ citations in Markdown, the LaTeX citation dialog lists Library sources, managed references.bib / references.json that never overwrite hand edits, Word export in a CSL style, and a pre-cite check for agents.
  • Identifiers (S3): arXiv and ISBN (Open Library, then Google Books) in the shared resolver; one "Add by identifier" input and scient_sources_add lists of mixed identifiers; a Library awareness block and tool hints for agents.
  • File import and export (S4): BibTeX/BibLaTeX, RIS, CSL-JSON and EndNote XML import through the existing preflight and duplicate check, keeping citation keys and listing what could not be kept; export of the Library or a selection to the same formats.
  • Reference check (S5): scient_references_check and "Check references" for .md, .tex, .bib and the Library (wrong or non-resolving DOIs, DOI naming another paper, retractions, preprints with a published version, missing fields), and a built-in references skill.
  • Zotero (S6): web API import with collections, notes, tags and Better BibTeX keys, refresh keeping local edits, and "Send to Zotero".
  • Papers (S7): scient_paper_get files papers as Sources (route and published/preprint version recorded); connector results resolve through the shared resolver; OpenAlex and Unpaywall slots in Accounts.
  • Full text (S8): text of every PDF page stored by file hash, scient_sources_search, exact Sources PDF quotes, quote verification, and browser "Save to Library".
  • Annotations (S9): highlights and notes on every PDF in .scient/annotations/v1/, agent read and write tools, and "Quote in my document".
  • Organise and review (S10): collections, tags, saved searches, bulk edit with one Undo (write-ahead receipts that survive partial failures), and systematic review v1 with logged searches, screening and a PRISMA 2020 flow.
  • Permissions: every Library change from the web client (26 HTTP mutations) is registered with the operate scope and runs through a guarded command (CLIENT_GUARDED_HTTP_SCOPES, createEnvironmentHttpCommand); read-only connections see the Library with change controls disabled. Server authorization is unchanged.
  • Header and polish: the Library header shows the title, Import sources and a ⋯ menu (Get missing PDFs, Check references, Systematic reviews, Export, Trash); the reference box no longer shifts Notes; the reference style picker opens on click; the search field reads "Search sources" so it fits narrow panes.
  • Work log and compiler: the 24 new tools have work-log names ("Prepared a citation", "Searched source text", …), and the Sources components no longer use try/finally in render code, so the React Compiler optimizes them again (shared settleAfter helper, as in FileRenameButton).
  • Paper requests: Get PDF on a source and paper requests that file or attach a source (accounts.papers.getForSource, accounts.papers.request with source or library: true) need orchestration:operate on top of settings:write, the same as the Sources routes. One rule (scientPaperRequestScopes) serves the client command check and the server authorization; malformed requests fail closed.
  • Live lookup checks: 42 cases against the real services through the app's own lookup modules (38 pass; the 4 failures are Google Books and Semantic Scholar 429s without keys, reported as unavailable, which is correct). Three fixes came out of it, each with a regression test built from the live response: old-style arXiv IDs with a subject class (math.DG/0211159), Open Library authors listed twice, and Crossref titles with inline markup read as plain text. The contact email went only to Crossref, OpenAlex and Unpaywall.
  • Main: origin/main ef51507463 is merged in; the only conflict was the measured budget file.
  • Agent tool list: descriptions of the new tools were shortened without changing any input. mcpToolListJsonBytes is 108,692 against main's 85,930, codexAdditionalContextAllCapabilitiesBytes 10,518 against 10,170, scientAwarenessAllCapabilitiesBytes 4,940 against 4,592. The new tools' input schemas alone account for about 14 KB, so the agent-context-budget check needs the agent-context-increase label.

S1 commits (on claude/sources-combined-20261110): e36d730419 (identifier checks and credit), 5458ffd9b5 (trash, restore, revert, robust listing), 511555a3f7 (contact email, PDF dates), 69ae7720d8 (retraction status, re-checks), d9ac2048cb (import-summary dismiss, review leftovers), afcbbc516b (tool-count test), 151a59517e (review fixes: unsafe JSON guard, permanent delete revision check under the lock).

Verification

Final gate on the combined branch (macOS, Apple Silicon), at e5c6034f40 and again after the last fixes at fffa6a6a66. After that, the head changes only work-log label wording the Accounts seam map (scient-accounts-seams.json, which classifies the two new files that read keys through Accounts) and one browser test that now calls the citation click handler directly instead of clicking by coordinates (it failed in a CI shard); packages/shared tests, typecheck and the server tool-presentation tests were re-run on it.

Re-gated at 6586b88e1f (paper-request permission and live-check fixes merged) and f3828bc76c (main ef51507463 merged; this PR's tree): vp fmt --check, vp lint --report-unused-disable-directives, pnpm run typecheck, git diff --check, every package and apps/mobile/apps/desktop test suite (except provider-fx, below), apps/web (15,458 tests; two timing failures under load in ExpandedImageDialog and MessagesTimeline, neither touched here, pass alone), pnpm run build and pnpm run test:desktop-smoke: pass. The full apps/server suite was stopped twice on this machine by load; the files that failed before it stopped were rerun alone on Node 26.12.1. OverleafStateStore and ProjectionStore pass. AntigravityInstallation (case-insensitive APFS), GitVcsDriverCore (/private/var), LatexRealEngine (needs the source-navigation helper) and two AcpAdapterV2 terminal-output tests still fail locally; none of these files is touched by this PR, and the full server suite passed in CI on the previous head. CI qualifies this head.

  • vp fmt --check, vp lint --report-unused-disable-directives, pnpm run typecheck, git diff --check, pnpm run build, pnpm run test:desktop-smoke: pass.
  • Package tests: all pass except packages/provider-fx skills.test.ts (2 tests; macOS /var vs /private/var paths; untouched by this branch).
  • apps/web (15,451 tests): pass apart from timing flakes under full-suite load that pass when rerun alone (useInlineActionConfirm in the first run, localApi in the second; neither file is touched). The full gate found 9 React Compiler coverage failures in Sources files; they are fixed here.
  • apps/server (15,959 tests): the full gate found one Sources failure, the missing work-log names, now fixed. Six other failures are environment-specific and reproduce on a clean checkout of main 9166d249c3: ProjectionStore SQL window, AntigravityInstallation, ProviderManagedExecution, GitVcsDriverCore (/private/var), LatexRealEngine (needs the source-navigation helper) and EnvironmentFileOpen (macOS file-watch timing; fails 8/8 on main when run alone).
  • Every stream, and each fix round, was reviewed by Codex gpt-6.1-sol until clean; reviews are in reviews/sources-roadmap-20261110/reviews/.
  • Visual: 252 screenshots (light/dark, 1440×900 and 900×800) from a seeded synthetic project, reviewed by Codex gpt-6.1-terra. One P3 finding (search placeholder) fixed. The PDF reader and cite flows have no narrow captures (harness limit).
  • All tests use fixtures or recorded responses; none reach the network. Live registry checks were run separately (above); the Zotero web API was not run live.

Documentation impact

Updated: docs/user/sources.md, docs/internals/scient-sources.md.

Model and harness

Streams built by Claude Opus 5.5 in Claude Code (Scient) and reviewed by Codex gpt-6.1-sol, screens reviewed by Codex gpt-6.1-terra; orchestrated by Claude Opus 5.5 in Factory Droid, then in Claude Code (Scient). PR 1 by Claude in Factory Droid.

🤖 Generated with Claude Code

@github-actions github-actions Bot added vouch:trusted Author is trusted by repo permissions or the VOUCHED list. size:XXL labels Nov 10, 2026
@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

Provider Metric Main baseline This PR Impact PR ceiling
Codex Total thread wire 5.5 KiB 5.5 KiB 0 B (0.0%) 6.8 KiB ✅
Codex Thread snapshot wire 4.2 KiB 4.2 KiB 0 B (0.0%) 4.9 KiB ✅
Codex Live turn WebSocket wire 1.3 KiB 1.3 KiB 0 B (0.0%) 2.0 KiB ✅
Codex Live turn WebSocket decoded 22.3 KiB 22.3 KiB 0 B (0.0%) 24.4 KiB ✅
Codex Live turn messages 1 1 0 (0.0%) 8 ✅
Claude Total thread wire 5.5 KiB 5.5 KiB 0 B (0.0%) 6.8 KiB ✅
Claude Thread snapshot wire 4.2 KiB 4.2 KiB 0 B (0.0%) 4.9 KiB ✅
Claude Live turn WebSocket wire 1.3 KiB 1.3 KiB 0 B (0.0%) 2.0 KiB ✅
Claude Live turn WebSocket decoded 22.7 KiB 22.7 KiB 0 B (0.0%) 24.4 KiB ✅
Claude Live turn messages 1 1 0 (0.0%) 8 ✅

Baseline: ef51507 · PR result: d7d239c · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.
Bounded compact HTTP snapshot with live cursor.

  • Codex decoded thread snapshot: 88.2 KiB
  • Claude decoded thread snapshot: 88.4 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.

@yaacovcorcos yaacovcorcos changed the title fix(sources): check agent identifiers and credit agent edits feat(sources): checked, credited and undoable Library writes Nov 10, 2026
@yaacovcorcos
yaacovcorcos force-pushed the claude/sources-agent-trust-20261110 branch 2 times, most recently from 8e2cb6a to 0eaf62f Compare November 11, 2026 02:39
yaacovcorcos added a commit that referenced this pull request Nov 11, 2026
…he click

The read-mode citation test clicks by coordinates. In a CI shard, earlier
tests left the editor below the viewport, so ProseMirror found no
position and the click was ignored (Test Web 5 on PR #823). Reproduced
locally by pushing the editor below the fold; scrolling it into view
first, as view.browser.test.ts does, fixes it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@yaacovcorcos
yaacovcorcos force-pushed the claude/sources-agent-trust-20261110 branch 3 times, most recently from 3d717e9 to c7744de Compare November 11, 2026 15:15
… Sources roadmap streams

One commit on main ef51507 with the tree of claude/sources-combined-20261110
at f3828bc plus its Accounts seam-map entry a6d25ea (full history, with each
stream's merges, stays on that branch).

- Phase 1: identifier-checked agent writes (doi.org, PubMed), updatedBy credit,
  review gate removed, trash, restore, revert, robust listing, contact email,
  retraction and correction status, re-checks.
- S2 citing and managed references.bib/json, S3 arXiv/ISBN and Add by
  identifier, S4 BibTeX/RIS/CSL-JSON/EndNote import and export, S5 reference
  check, S6 Zotero, S7 papers filed as Sources, S8 full-text search and quote
  checks, S9 PDF annotations, S10 collections, tags, saved searches, bulk edit
  with Undo and systematic reviews.
- Client permission gating for Library HTTP mutations, a trimmed agent tool
  list, Library header and reference-box fixes, work-log names for the new
  tools, and React Compiler-safe busy-state handling.
- Paper requests that file or attach a source (Get PDF, library requests) now
  need the same Library permission as the Sources routes, checked by one rule
  on client and server.
- Fixes from live lookup checks: old-style arXiv IDs with a subject class,
  Open Library authors named twice, and Crossref titles with inline markup
  read as plain text.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
@yaacovcorcos

Copy link
Copy Markdown
Contributor Author

Superseded by #881, which carries this PR's agent-trust work together with the rest of the Sources stack (M2 and the personal Library), squashed onto current main and gated together. Leaving this open for the owner to close.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

size:XXL vouch:trusted Author is trusted by repo permissions or the VOUCHED list.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant