CAP Open Protocol

CAP, the CiteArk Artifact Protocol, exchanges immutable research graph snapshots. A paper is an optional source entity or a presentation of research. Research without a paper uses the same model.

Scientific objects

A plan is an Entity, not evidence that an Activity occurred. Observations retain values, units, conditions, provenance and known limitations. Assessments separately identify their subject, evidence, method, assessor, scope, limitations and conclusion. Conflicting assessments remain available.

Activity states are running, succeeded, failed, cancelled, partial, timedOut, unknown. Assessment conclusions are supports, challenges, contradicts, inconclusive. Success of execution does not imply support for a claim.

Identity and revision

A Record has a producer-namespaced logical ID and an exact content digest. A revision keeps the logical identity and creates a new digest. Each snapshot contains at most one version of a logical ID. Equal titles or statements do not merge objects. One actual execution may serve several claims without becoming several independent executions.

Manifests and normative JSON records use RFC 8785 canonical JSON. Scientific decimal values are strings, for example {"decimal":"81.900000"}. The manifest never embeds its own digest. Adding a detached signature or repacking an archive does not change the scientific artifact identity.

Relations and sources

Each Relation contains a predicate, subject, object, author, sources, basis and optional qualifiers. Its endpoints use {ref, digest, recordType}; a cross-artifact endpoint adds artifactDigest. Local domain bindings may use {ref} because the immutable manifest fixes their version; scientific Relation endpoints always carry exact digests.

Basis distinguishes observed, declared, inferred, attested. A signature does not upgrade a declaration into an observation. An unresolved reference is a declared dependency; it is not fetched automatically or counted as verified evidence. A digest grants no access to private data.

Bundle and materials

The transport is .cap, a tar+gzip archive with media type application/vnd.citeark.cap+tar+gzip;version=2.

cap-manifest.json
records/sha256/<prefix>/<digest>.json
blobs/sha256/<prefix>/<digest>
attestations/
preview/
projections/
cap-locations.json
ro-crate-metadata.json

The manifest uses https://citeark.com/schemas/cap/v2/manifest.schema.json, media type application/vnd.citeark.cap.manifest.v2+json, version 2.0.0-alpha.2, creator, profiles, roots, records, blobs and artifact-level relations. Scientific type URIs and profile URIs end in /2.0.

Blob descriptors fix digest, size, media type, roles and availability: embedded, external, withheld. Restricted material may remain unavailable. Dataset and model identity does not require packaging their bytes. Unsafe paths, duplicate entries, links, devices, undeclared scientific files and invalid hashes are rejected. Locations and previews are detached presentation data.

Profiles and trust

Core does not require a paper, hosted task or execution. Research Compilation records source-grounded understanding; Research Plan records prospective procedures and targets; Computational Run records actual execution; Reproduction adds reference work, scope and assessment bindings. Agent Trace, Restricted Evidence and Public Bundle add their respective constraints.

Reproduction retains blinded execution and a precommitted verification policy. The commitment algorithm remains citeark-policy-commitment-v1; that algorithm name does not mean the bundle uses CAP 1. Assessment reveals and verifies the commitment without changing original observations.

Detached attestations use Ed25519, DSSE and an in-toto Statement v1. CAP predicate type is https://citeark.com/cap/attestations/artifact/v2. Valid signature, trusted signer, authentic execution, independent repetition and scientific support are separate findings. Hosted admission additionally validates task and repository bindings; an independent signature never grants platform identity.

Per-resource rights stay attached to materials. Public metadata does not grant redistribution rights for a paper, dataset, model or code. RO-Crate and provenance mappings are projections, not a replacement for CAP validation.

Agent traces

Capture retained workflow instructions, model/provider identity when known, tool calls, commands, inputs, outputs, patches, explicit decisions, errors and retries. Prompts and traces are Entities with optional Blob material. Large transcripts are optional; hidden chain-of-thought is neither required nor claimed to be captured.

Disclosure states the actual retained level and redactions. A digest-only prompt cannot be advertised as retrievable text. Agent-writable helper logs remain declarations; missing training or analysis phases are not inferred from command names. Reassessment reuses Activity and observation bytes and adds a new assessment linked to its predecessor.

ArkGraph queries and publication

The website and Agent share query rules arkgraph/1: subgraph, exact record, route, route comparison and provenance. A route may branch or share inputs. Comparison fixes both artifact scopes and target versions; it preserves conflicting judgments. Truncated or inaccessible dependencies remain unknown. Different digests do not establish independence.

citeark-agent graph --cap result.cap --operation subgraph
citeark-agent graph --cap result.cap --operation route --query route.json
citeark-agent graph --server https://citeark.co --query query.json

POST /api/v1/graph and MCP query_research_graph use the same contract. Upload signed CAP through POST /api/v1/artifacts, MCP publish_research_artifact, or the research artifacts page. Publication defaults to private; paper association is optional. Reproduction results bind their own plan. See Agent API and local execution.

Research-object granularity

Datasets, exact splits, model architectures, checkpoints and code revisions can be separate Entities. procedure-step records explicit scientific steps and shared inputs. Expected outputs remain prospective specifications with prospective: true. Source-reported measurements, execution observations and bounded measurement-assessment judgments are separate nodes. A supported measurement never promotes an incompletely assessed claim. Object relationships come from signed CAP records; equal names do not merge identities.