Skip to content

vox-scientia API Reference (generated)

Crate: vox-scientia · Version: 0.6.0 · Target: Library (lib.rs)

SCIENTIA research-pipeline cluster umbrella: producers, replay, manuscript (IMRaD/LaTeX), critic gate, class routing, findings site, dashboard, plus claim-extractor / inspect-bridge / nanopub / ro-crate / ingest sub-modules.

SCIENTIA knowledge platform integration components.

Modules that correspond to architecture plan phases:

  • Phase A producers: producers
  • Phase B replay runner: replay
  • Phase C–4 manuscript pipeline: manuscript
  • Phase D critic gate: critic_gate
  • Phase E class routing: class_routing
  • Phase G findings site: findings_site
  • Phase H dashboard JSON: dashboard

Now-present sub-modules (formerly tracked as planned crates in layers.toml): claim_extractor, inspect_bridge, nanopub, ro_crate, ingest. Pre-registration is orchestrator-owned (vox-orchestrator/src/preregistration/), not planned in this crate.

DependencyKind
vox-actor-runtimeNormal
vox-configNormal
vox-cryptoNormal
vox-dbNormal
vox-db-typesNormal
vox-http-clientNormal
vox-research-eventsNormal
vox-searchNormal
vox-secretsNormal
ModuleDescription
claim_extractor—
ingest—
inspect_bridge—
nanopub—
ro_crate—
producers—
replay—
manuscript—
critic_gate—
class_routing—
findings_site—
dashboard—
review—
review_flow—
evidence_assist—
Dependency Topology, diagram 117 nodes, 16 edges: vox-scientia → vox-actor-runtime; vox-scientia → vox-config; vox-scientia → vox-crypto; vox-scientia → vox-db; vox-scientia → vox-db-types; vox-scientia → vox-http-client; vox-scientia → vox-research-events; vox-scientia → vox-search; vox-scientia → vox-secrets; vox-cli → vox-sc…vox-scientiavox-actor-runtimevox-configvox-cryptovox-dbvox-db-typesvox-http-clientvox-research-eventsvox-searchvox-secretsvox-clivox-cli-researchvox-guivox-orchestrator-mcpvox-plugin-publicationvox-publishervox-research-shim
Diagram source
graph {
direction: right
node vox_scientia: "vox-scientia"
node vox_actor_runtime: "vox-actor-runtime"
vox_scientia -> vox_actor_runtime
node vox_config: "vox-config"
vox_scientia -> vox_config
node vox_crypto: "vox-crypto"
vox_scientia -> vox_crypto
node vox_db: "vox-db"
vox_scientia -> vox_db
node vox_db_types: "vox-db-types"
vox_scientia -> vox_db_types
node vox_http_client: "vox-http-client"
vox_scientia -> vox_http_client
node vox_research_events: "vox-research-events"
vox_scientia -> vox_research_events
node vox_search: "vox-search"
vox_scientia -> vox_search
node vox_secrets: "vox-secrets"
vox_scientia -> vox_secrets
node vox_cli: "vox-cli"
vox_cli -> vox_scientia
node vox_cli_research: "vox-cli-research"
vox_cli_research -> vox_scientia
node vox_gui: "vox-gui"
vox_gui -> vox_scientia
node vox_orchestrator_mcp: "vox-orchestrator-mcp"
vox_orchestrator_mcp -> vox_scientia
node vox_plugin_publication: "vox-plugin-publication"
vox_plugin_publication -> vox_scientia
node vox_publisher: "vox-publisher"
vox_publisher -> vox_scientia
node vox_research_shim: "vox-research-shim"
vox_research_shim -> vox_scientia
}
Consumer CrateRole
vox-cliDirect workspace dependent
vox-cli-researchDirect workspace dependent
vox-guiDirect workspace dependent
vox-orchestrator-mcpDirect workspace dependent
vox-plugin-publicationDirect workspace dependent
vox-publisherDirect workspace dependent
vox-research-shimDirect workspace dependent
KindSymbolSignatureSourceDescription
structevidence_assist::EvidenceSuggestionpub struct EvidenceSuggestioncrates/vox-scientia/src/evidence_assist.rs#L23-L30One advisory suggestion for improving a claim’s evidence or conclusion. kind is one of evidence_gap | conclusion_refinement | novelty_check.
fnevidence_assist::build_promptpub fn build_prompt(crates/vox-scientia/src/evidence_assist.rs#L37Build the (pure) chat prompt for the evidence-assist call. The first message is a system message instructing the model to emit a JSON array of suggestion objects; the second is a user message embedding the claim text and any known verdict/confidence. Pure + unit-testable: no I/O.
fnevidence_assist::parse_suggestionspub fn parse_suggestions(raw: &str) -> Vec<EvidenceSuggestion>crates/vox-scientia/src/evidence_assist.rs#L80-L83Parse a raw LLM response into a suggestion list. Strips Markdown code fences first, then parses a JSON array. Returns Vec::new() on any parse failure (never panics) — this is advisory output.
fnevidence_assist::suggestpub async fn suggest(crates/vox-scientia/src/evidence_assist.rs#L90Produce advisory evidence/conclusion suggestions for a claim. Routes through the [vox_actor_runtime::llm] facade. ANY error (no key, network failure, unparseable output) degrades to Vec::new() so the review flow is never broken by this advisory path.
structingest::FeedSourcepub struct FeedSourcecrates/vox-scientia/src/ingest/mod.rs#L13-L18A registry feed source endpoint (e.g. RSS URL) for inbound research scoping.
structingest::InboundItempub struct InboundItemcrates/vox-scientia/src/ingest/mod.rs#L22-L27A raw scraped/received item before semantic evaluation.
fnreplay::run_replaypub async fn run_replay(crates/vox-scientia/src/replay/mod.rs#L34Execute main_entity in a fresh sandbox under stage_dir and produce a [ReplayReport]. stage_dir must already contain whatever artifacts the entry-point expects to read; caller is responsible for staging. The runner only re-executes the entry-point and verifies declared outputs.
traitreview::Sealedpub trait Sealedcrates/vox-scientia/src/review/mod.rs#L35—
traitreview::ReviewDecisionLikepub trait ReviewDecisionLike: sealed::Sealedcrates/vox-scientia/src/review/mod.rs#L43-L49Abstraction over any type that carries enough data to mint an [ApprovalToken]. Implemented here for [vox_db::store::ReviewDecisionRow]; unit tests use a tiny in-module fake. Sealed (see sealed) — cannot be implemented outside this crate.
structreview::ApprovalTokenpub struct ApprovalTokencrates/vox-scientia/src/review/mod.rs#L83-L91A cryptographic proof that a specific claim was approved by a human reviewer. # compile-fence: All fields are private; there is no pub constructor and no Default. Struct-literal construction outside this module is a compile error: compile_fail let _ = vox_scientia::review::ApprovalToken { claim_id: 1, bound_digest: String::new() };
fnreview::claim_idpub fn claim_id(&self) -> i64crates/vox-scientia/src/review/mod.rs#L104-L106The claim that was approved.
fnreview::publication_idpub fn publication_id(&self) -> &strcrates/vox-scientia/src/review/mod.rs#L111-L113The publication the approval is scoped to; nanopub_build rejects a token whose publication_id differs from the build’s, preventing cross-publication replay.
fnreview::bound_digestpub fn bound_digest(&self) -> &strcrates/vox-scientia/src/review/mod.rs#L120-L122The digest bound at approval time (expected to be the publication’s SHA3-256 content_sha3_256, but not validated by this module — the token trusts the caller). Binds the token to the exact artifact version reviewed by the human; Task 3 rejects a token whose digest no longer matches the current manifest, so an edit invalidates a stale approval.
fnreview::mint_from_decisionpub fn mint_from_decision<D: ReviewDecisionLike>(d: &D) -> Option<ApprovalToken>crates/vox-scientia/src/review/mod.rs#L131-L141Returns Some(token) only when d.decision() == "approved"; returns None for rejected, deferred, edited, or any other value. This is the sole construction path for [ApprovalToken].
enumreview::ReviewStatepub enum ReviewStatecrates/vox-scientia/src/review/mod.rs#L147-L160The lifecycle state of a nanopublication claim in the review pipeline.
enumreview::ReviewActionpub enum ReviewActioncrates/vox-scientia/src/review/mod.rs#L164-L178Actions that drive transitions in the review state machine.
fnreview::next_statepub fn next_state(current: ReviewState, action: ReviewAction) -> ReviewStatecrates/vox-scientia/src/review/mod.rs#L197-L210Pure state-machine transition function. Invalid transitions (e.g. Surfaced + Approve) return current unchanged. Valid transitions: text Surfaced + StartReview → UnderReview UnderReview + Approve → Approved UnderReview + Reject → Rejected UnderReview + Defer → Deferred UnderReview + Edit → Edited Edited + ReSurface → Surfaced Deferred + ReSurface → Surfaced Approved and Rejected are terminal (no outgoing transition). Deferred and Edited are recoverable — both re-enter the queue via ReSurface.
fnreview_flow::publication_session_idpub fn publication_session_id(publication_id: &str) -> i64crates/vox-scientia/src/review_flow.rs#L34-L41Derive a stable session_id from a publication id (FNV-1a). scientia_claims is keyed by session_id; a publication’s extracted claims share this bucket.
fnreview_flow::resolve_or_create_identitypub async fn resolve_or_create_identity(crates/vox-scientia/src/review_flow.rs#L80Get-or-create the per-user nanopublication signing identity. 1. Reads the stored user_identities row (if any). 2. Chooses an ORCID: the orcid arg wins; else the stored orcid_id; else errors (the nanopub crate requires an https://orcid.org/ identity to sign). 3. Resolves the private key from the vault. If a row exists AND the key resolves, REUSES that material. 4. Otherwise GENERATES a fresh RSA keypair, stores the private key in the vault, and upserts the public key + ORCID + key-ref into the DB. Returns a [NanopubProfile] whose name is the user_id. # Errors Returns an error if no ORCID can be determined, if RSA keygen fails, if the vault write fails, or if any DB op fails.
fnreview_flow::nanopub_buildpub async fn nanopub_build(crates/vox-scientia/src/review_flow.rs#L163P1 — Build a spec-compliant, RSA-signed, OFFLINE-validated nanopublication for a single extracted claim, then persist it locally. This function performs NO network publishing of any kind (no publish, no test server). Steps: 1. Load the claim row + its latest verdict from the SCIENTIA claim ledger (errors helpfully if absent — run publication-extract-claims first). 2. Resolve (or create) the per-user RSA + ORCID signing identity. 3. Assemble the enriched assertion Turtle and RSA-sign it (build + sign). 4. VALIDATE the signed TriG OFFLINE (trusty hash + signature). Fails hard if invalid — nothing is persisted on a validation failure. 5. Persist a scientia_nanopubs row with published_state="local" and validated_offline=true. Returns the [SignedNanopubDoc] (Trusty URI + signed TriG). The caller prints a short human line (the Trusty URI) — this function deliberately writes NOTHING to stdout, but note that [crate::nanopub::spec::validate_offline] internally calls the upstream nanopub crate’s check(), which prints a ✅ ... is valid line to stdout on success. A strict --json mode for this command therefore needs upstream stdout suppression and is deferred. # Errors Returns an error if the claim/verdict is missing, if no ORCID is available, if signing fails, if offline validation fails, or if any DB op fails.
fnreview_flow::nanopub_publish_test_serverpub async fn nanopub_publish_test_server(crates/vox-scientia/src/review_flow.rs#L330Publish an already-built local nanopub to the nanopub TEST server. Requires BOTH: - token: an [crate::review::ApprovalToken] — only mintable from a persisted human “approved” decision (non-constructible outside crate::review). - VOX_NANOPUB_TEST_SERVER=1 in the environment — checked inside [crate::nanopub::network::publish_to_test_server] via [crate::nanopub::network::ensure_test_server_allowed]. Production publishing is deliberately unimplemented (standing decision). Steps: 1. Verify the token is bound to the correct publication_id and claim_id (same cross-publication / claim-identity guard as [nanopub_build]). 2. Load the persisted scientia_nanopubs row by looking up all rows for the claim’s session and finding the one with the matching Trusty URI (the local artifact built by a prior nanopub_build call). 3. Resolve the signing identity (ORCID + private key). 4. Call [crate::nanopub::network::publish_to_test_server] with the stored signed TriG + profile. 5. Update the row’s published_state to "test_server" via the DB op. Returns the published URI (the Trusty URI the test server accepted). # Errors Returns an error if the token mismatches, if no local nanopub exists for the claim, if the env gate is not set, if the network call fails, or if any DB op fails.
fnreview_flow::record_claim_reviewpub async fn record_claim_review(crates/vox-scientia/src/review_flow.rs#L409P2 Task 4 — Record a human review decision for ONE extracted claim. Fetches the publication’s CURRENT content manifest and binds the decision to its content_sha3_256 digest. A later content edit therefore invalidates a prior approval (the digest will no longer match the manifest’s current value), and publication-nanopub-build will refuse to emit until the claim is re-reviewed. # Errors Returns an error if no manifest exists for publication_id, if db.record_review_decision rejects the decision string, or if any DB op fails.
fnreview_flow::approval_forpub async fn approval_for(crates/vox-scientia/src/review_flow.rs#L468P2 — Bridge the DB review ledger to a minted [ApprovalToken]. This is the only sanctioned way for the CLI to obtain the token that [nanopub_build] now requires. It is a thin, testable boundary so the “not approved → refused” path can be exercised without the live-DB CLI arm. 1. Look up the LATEST review decision for claim_id. Absent → error telling the operator to run publication-claim-review first. 2. Mint a token via [crate::review::mint_from_decision], which returns Some ONLY when the latest decision is "approved". Any other status (rejected/deferred/edited) yields None → error. [ApprovalToken]: crate::review::ApprovalToken # Errors Returns an error when no decision exists, when the latest decision is not "approved", or when the underlying DB op fails.
structreview_flow::PromotedPublicationpub struct PromotedPublicationcrates/vox-scientia/src/review_flow.rs#L500-L507Summary returned when promoting a finding candidate or research session to a canonical publication_manifests row.
fnreview_flow::resolve_manifest_or_promotepub async fn resolve_manifest_or_promote(crates/vox-scientia/src/review_flow.rs#L559Resolve a publication_manifests row by publication_id or source_ref (finding-...), auto-promoting a matching scientia_finding_candidates row if not yet promoted.
fnreview_flow::promote_candidate_to_publicationpub async fn promote_candidate_to_publication(crates/vox-scientia/src/review_flow.rs#L595Promote a scientia_finding_candidates row, discovery inbox item, or research session into a canonical publication_manifests draft and seed its verified claims in scientia_claims.
fnreview_flow::assemble_scaffold_from_dbpub async fn assemble_scaffold_from_db(crates/vox-scientia/src/review_flow.rs#L932Hydrate a [crate::manuscript::scaffold::ScaffoldInput] directly from VoxDb (publication_manifests + scientia_claims + scientia_nanopubs) with zero manual JSON files.
fnreview_flow::assemble_finding_page_from_dbpub async fn assemble_finding_page_from_db(crates/vox-scientia/src/review_flow.rs#L1043Hydrate a [crate::findings_site::FindingPage] directly from VoxDb with zero manual JSON files.
fnreview_flow::record_replay_for_publicationpub async fn record_replay_for_publication(crates/vox-scientia/src/review_flow.rs#L1123Write a measured artifact_replayability score (0.0..=1.0) into publication_manifests.metadata_json.scientia_evidence.artifact_replayability and append an artifact_replayability_measured status event.
fnreview_flow::assemble_scientia_queue_from_dbpub async fn assemble_scientia_queue_from_db(crates/vox-scientia/src/review_flow.rs#L1233Assemble a unified [crate::dashboard::QueueSnapshot] from publication_manifests AND scientia_finding_candidates, with real confidence scores and reply-window tracking.
fnreview_flow::assemble_scientia_cost_from_dbpub async fn assemble_scientia_cost_from_db(crates/vox-scientia/src/review_flow.rs#L1340Assemble a [crate::dashboard::cost::CostRollup] from VoxDb for the current quarter.