ResearchWorkspace

Purpose and authority boundary

NexusScholar.ResearchWorkspace coordinates local files around the domain packages. It discovers nexus.project.json, imports user-selected Search exports, verifies bytes, publishes analysis and authority generations, reconstructs current authority, prepares read models, and commits admitted local transitions.

It is an application-service boundary, not a domain model. The project index and its paths are commit pointers and locators. Scientific authority remains in canonical, digest-bound records inside verified generations.

A filename such as current.deduplication-result.json is never trusted by convention alone. Consumers resolve it through the committed project pointer and verify the generation manifest, artifact path, bytes, digest, workspace id, revision, and upstream bindings.

Workspace layout and commit protocol

nexus.project.json                 final atomic commit pointer
inputs/search/                     immutable imported source bytes
nexus-output/generations/          analysis generations
nexus-output/authority-generations/
nexus-output/workflow-executions/
nexus-output/screening-conducts/
nexus-output/screening-authority-packages/
nexus-output/fulltext-generations/
nexus-output/exports/
nexus-output/.staging/             uncommitted preparation
nexus-output/quarantine/           promoted but uncommitted recovery

Writers prepare a generation in staging, hash and verify every artifact, acquire an exclusive workspace lock, re-read the project, compare the exact expected revision and source pointers, atomically promote the directory, then replace nexus.project.json last. A failed post-promotion commit is quarantined.

Project revisions are monotonic concurrency tokens. Authority generations may remain valid across later unrelated revisions only when their generation id and manifest digest remain unchanged; writers still require an exact expected revision.

Major API families

• ResearchWorkspaceLocalOperations: initialize a folder and import local CSV, RIS, or BibTeX Search evidence with source digest, parser trace, warnings, and skipped-record counts.
• ResearchWorkspaceVerifier: verify inputs, reject absolute/escaping/reparse-point paths, reparse evidence, and report missing or changed bytes.
• ResearchWorkspaceTransaction: atomic analysis, FE-01 authority initialization, and FE-02 successor decision commits.
• ResearchWorkspaceAuthorityChainVerifier: replay baseline and successor authority generations into verified policy, snapshots, decisions, invalidations, and provenance.
• ResearchWorkspaceDeduplicationReview: inspect queue, preview exact effects, and commit a verified human deduplication decision.
• ResearchWorkspaceScreeningAuthorityPackage: persist and reconstruct the exact approved Protocol, title/abstract criteria, Deduplication result, decision set, and corpus snapshot needed for future Screening conduct.
• ResearchWorkspaceWorkflowExecutionJournal*, ResearchWorkspaceScreeningConduct*, and ResearchWorkspaceFullText*: verified generation transactions for later workflow stages.
• ResearchWorkspaceExportLedger*: digest-linked, human-recorded local export history with exact report/bundle inventory.
• ResearchWorkspaceReadModelBuilder: framework-neutral status, imports, evidence rows, duplicate clusters, review queues, and attention items.

Structured outcomes and failure semantics

Local operations return Succeeded, Failed, Stale, or RecoveryRequired. Desktop adapters add an Attention presentation state. Absence of an exception is never treated as proof of success.

• Stale: expected revision, workspace id, source digest, generation id, manifest digest, decision set, snapshot, or target no longer matches.
• Failed: missing project/input, unsupported schema/format, malformed canonical content, or a domain rule refusal.
• Recovery required: lock contention, I/O interruption, active authority transition, or state that cannot safely be classified as a normal validation failure.
• Already applied: replay-safe requests can return the previously committed transition rather than duplicating it.

Dependencies and extension points

The project references the domain and bridge packages it must orchestrate plus AppServices and UiContracts. It must remain UI-framework-free and provider-free. CLI and Desktop.AppServices adapt its structured operations; neither should duplicate its transaction engine.

New durable workflow stages should add a generation manifest, strict verifier, staging/promotion transaction, pointer-last project update, explicit result states, replay behavior, and adversarial tests. Adding a mutable “current” file without a verified generation is not an acceptable extension.

Tests and accepted evidence

ResearchWorkspace tests cover local services, generation verification, authority artifacts, authority transitions, Screening authority packages, concurrency, fault injection, stale writes, quarantine, path safety, read models, Full Text, Screening conduct, workflow journals, and exports.

The key architecture contracts are ADR 0016, ADR 0023, and the FE-08 authority decisions 0035–0037.

Explicit nonclaims

No database, API, cloud synchronization, multi-user locking protocol, remote provider, authentication, identity provider, installer, telemetry, PHP compatibility, or production-security claim is made. The workspace is a disciplined local folder protocol, not a distributed transaction system.