paper-atlas/docs/annotations.md

Research types and custom annotations

Research type describes a claimed characteristic of the work (for example a survey, benchmark, empirical study or replication). It is independent of topic, paper length, conference track, presentation format and acceptance status. No type is inferred from those fields. Multiple source-specific or human classifications may coexist; no cross-platform vocabulary mapping or automatic classifier is provided.

annotation_events stores both kinds with an explicit kind discriminator: research_type and tag are separate domains, even when namespace/value strings happen to coincide. Existing platform labels remain in tags / paper_tags. Each assertion carries namespace, value, actor, reason, evidence key, optional source record and evidence URL, and the time it was recorded. This is observation time, not paper publication time or a conference decision date.

Values are not forced into a global taxonomy: custom:method=empirical and platform:declared_type=empirical retain separate provenance. An explicit platform assertion API requires a source record belonging to that paper and matching the namespace prefix. The manual CLI only accepts custom:*, and cannot retract platform assertions. No source type has been automatically assigned to existing papers.

Initialize explicitly

On the published PostgreSQL dataset, using its protected service file:

PGSERVICEFILE=/etc/paper-atlas/pg_service.conf paper-atlas annotate init \
  --pg-service foundry-research --pg-schema research

This creates one optional table, its indexes, and an upgrade marker in one transaction, using the existing dataset writer lock. It does not copy data, change existing papers or decisions, or create a PostgreSQL instance. Repeating it is safe; an unexplained pre-existing table/marker mismatch fails closed. Readers and ordinary imports do not install the extension. Legacy datasets remain readable. A SQLite sample uses --db sample.sqlite; the cutover SQLite backup remains protected against writes.

Add and retract evidence

Use the canonical paper ID returned by query. For a reviewed classification:

paper-atlas annotate assert --pg-service foundry-research --pg-schema research \
  --paper "$PAPER_ID" --kind research_type --namespace custom:method \
  --value empirical --evidence-key manual:abstract-review \
  --actor reviewer --reason 'Classified from the explicitly described study design' \
  --request-id "$REQUEST_ID"

$REQUEST_ID must be a new, stable identifier for this action (for example a UUID). Retry with the same request ID and identical content after an interrupted response; it returns the original event ID. Reusing that ID with changed content is rejected. A topic annotation uses --kind tag --namespace custom:topic --value robotics instead. Optional --source-record and --evidence-url attach additional evidence; the source record must belong to this paper. URLs are retained as evidence and are not fetched.

To withdraw one particular assertion, use its returned event ID:

paper-atlas annotate retract --pg-service foundry-research --pg-schema research \
  --event "$EVENT_ID" --actor reviewer --reason 'Classification corrected after review' \
  --request-id "$RETRACTION_REQUEST_ID"

Retraction adds an event referencing that assertion, preserving its original content. It does not remove another contributor's assertion of the same label, platform tags, source metadata or submission/decision history. A retracted assertion can be asserted again with a new request ID and evidence; it is a new observation. The API does not update or delete past annotation events. Database administrators still control direct SQL access. Work reviewed as the same paper may subsequently be merged by the existing identity workflow: annotation IDs, original paper IDs, evidence and retraction links are retained while the canonical paper reference follows the surviving entity.

Query and analyze

paper-atlas query --pg-service foundry-research --pg-schema research \
  --research-type custom:method=empirical
paper-atlas query --pg-service foundry-research --pg-schema research \
  --tag custom:topic=robotics
paper-atlas query --pg-service foundry-research --pg-schema research \
  --paper "$PAPER_ID" --annotation-history
paper-atlas annotate list --pg-service foundry-research --pg-schema research \
  --paper "$PAPER_ID" --history

--tag includes original platform labels and active annotation tags. It never matches research types. --research-type matches active type assertions only. Paper details return separate tags (existing provenance), annotation_tags, and research_types; --annotation-history additionally includes retractions. A missing extension yields empty annotation results rather than changing the database.

For direct SQL analysis, active research-type evidence is:

SELECT a.* FROM research.annotation_events a
WHERE a.kind = 'research_type' AND a.retracts_id IS NULL
  AND NOT EXISTS (SELECT 1 FROM research.annotation_events r WHERE r.retracts_id = a.id);

Several independent assertions can support one label; count distinct papers/labels when appropriate rather than counting evidence rows as papers. Namespaces stay separate. Standard paper queries decode the PostgreSQL text codec; direct SQL consumers must honor the dataset's documented codec, including NUL/SOH values. SQLite-to-PostgreSQL migration recognizes an installed annotation extension and verifies its full row hashes, constraints and identity sequence along with the original business tables. An old 21-table snapshot stays a 21-table migration; no synthetic annotations are generated.