Core Concepts

CiteArk turns every paper into a "research repository". A repository's complete state at a point in time (its snapshot) is built from a single object chain: once the paper is structured, verifiable Claims are extracted; Claims link to experiment plans; experiments are actually executed and produce run records; runs leave evidence objects behind and are sealed with a signed attestation.

Paper
  └── Claim            a verifiable scientific finding extracted from the paper
       └── Experiment   the experiment plan that tests the claim
            └── Run      a record of one real execution
                 ├── Evidence      metrics, artifacts, logs, etc. produced by the run
                 └── Attestation   a signed attestation of this execution

The research repository snapshot

GET /api/repositories?owner=<owner>&slug=<slug> returns { "repository": … }, the repository snapshot. Top-level fields:

Claims

A Claim is a verifiable scientific finding extracted from a paper.

verification status enum: unverified, review_required, queued, running, verified, failed, inconclusive, cancelled, timed_out.

Experiments

An Experiment is a plan for testing a set of claims.

Two kinds of executor:

• builtin: the controlled private-beta executor (handler ara-structure-v1, recording sourceRepository, sourceCommit, and requiredPaths). The production reproduction queue currently only accepts experiments with this executor.
• agent: an Agent executor, with availability of private-beta or unavailable.

Runs

Reproduction requests are asynchronous: a successful POST /api/runs returns 202 with a run record in state=queued, and execution proceeds in the background after the response. Clients poll runs[] in the repository snapshot until the run reaches a terminal state (verified / failed, etc.).

Key RunRecord fields:

Evidence & Content Addressing

Evidence is an evidence object produced by a run: kind is one of metric / artifact / log / checkpoint / figure, plus digest, uri, generatedByRunId, and summary. Evidence supports verification; runs[].outputs records what the execution scientifically produced. A single content-addressed file may serve both roles.

All binary objects are content-addressed: digest is the sha256 of the content. Downloads go through GET /api/objects/{64-char hex} (the digest without the sha256: prefix); the response header x-content-sha256 carries the full sha256:<hex>, so callers can recompute the sha256 of what they downloaded and compare it to verify integrity. The server also checks the stored object's digest and byte count before responding, returning 502 on mismatch.

Attestation

Every run carries an execution attestation (AttestationRecord): statementDigest, nodeId, keyId, algorithm (ed25519 / ecdsa-p256 / pending), signature, signedAt, and transparencyLog (the Transparency Log's index, entryDigest, previousEntryDigest). A freshly queued run's attestation is pending; it is signed only after execution completes.

Query an attestation by statementDigest: GET /api/attestations/{64-char hex} returns:

{
  "attestation": { "statementDigest": "sha256:…", "signature": "…", "transparencyLog": { "index": 1, "entryDigest": "sha256:…" } },
  "verified": true,
  "verificationMethod": "ECDSA P-256 over CiteArk canonical JSON"
}

verified is not a stored flag — it is the result of the server re-verifying the signature with the public key in the attestation at response time.

The three verification rings: Run · Match · Repeat

Run · Match · Repeat is CiteArk's shared trust language. The logic lives in deriveVerificationRings in src/domain/rings.ts:

• Run: some run in runs[] has state=verified — the code actually ran.
• Match: some verified run's claimIds intersect the set of claims with verification=verified — the run's results support the values the paper reports.
• Repeat: some claim has successfulIndependentRuns > 0 — an independent Agent / runner / environment has reproduced it successfully.

The three rings are strictly progressive: successfulIndependentRuns only increments when an independent reproduction is verified, so when Repeat is lit, Match and Run are necessarily lit too (Repeat ⇒ Match ⇒ Run). All three rings can only be lit by real execution evidence — never by textual judgment alone.

Filled dots and outer circles have different meanings. ●●● means Repeat. The dots become ◉◉◉ only at L5, after a paper author or trusted institution has signed the exact Artifact root. A runner attestation, community reproduction, or Agent-written conclusion must never create the outer circles.

Badge levels share the same source as the rings (src/domain/badge.ts): L2 reproduced = Match, L1 executed = Run, L0 indexed = compilation.state === verified.

License Gate

The snapshot's licenseGate field records the license assessment:

Assessment rules (assessLicense in src/domain/license.ts, matched in order):

1. Submitter has not attested ownership (submitterAttested=false) → red;
2. The paper license is in the open set (CC0-1.0, CC-BY-4.0, CC-BY-SA-4.0, MIT, Apache-2.0) and the code license permits execution (absent, no-code, or one of MIT, Apache-2.0, BSD-2-Clause, BSD-3-Clause, ISC, MPL-2.0, GPL-3.0-only) → green;
3. Paper license is publisher-restricted → red;
4. Everything else → yellow.

Derived fields:

• discoverable and executable follow the submitter attestation and do not depend on redistribution rights;
• redistributable is true when the submitter attested and the paper license itself is open; it does not depend on the separate code-license assessment;
• artifactPublishable covers CiteArk-generated metrics, logs, traces, typed scientific outputs, attestations, and verification records. CAP files never include third-party paper, repository, dataset, or checkpoint source payloads; a dataset or checkpoint genuinely produced by the recorded run may be published as a derived output when its license permits it.

License status is therefore a source-handling and risk label, not an ingestion or execution gate. Yellow and red repositories can still be discovered and executed; their source materials remain link-only unless redistribution is explicitly permitted.

Downloading a paper PDF whose license forbids redistribution via /api/objects returns 451 ("the paper's license does not allow CiteArk to redistribute it; visit the original source"), and the page only links back to the original source.

Public projection

The repository snapshot is an internal read model. When a non-owner reads a public repository, the snapshot passes through the public projection (src/server/public-projection.ts) before serialization:

• Internal storage URIs (r2://, etc.) in sources[], evidence[], and runs[].outputs[] are rewritten to /api/objects/<hex>; external URLs have credentials and sensitive query parameters stripped;
• requestedBy is erased from runs[];
• run.log keeps only the system / stdout streams, each message truncated to 4000 characters, with Bearer tokens and assignments like api_key / token / secret / password / authorization redacted.