CAP Open Protocol

CAP, the CiteArk Artifact Protocol, is an open protocol for immutable, content-addressed and independently verifiable scientific snapshots. It lets a researcher, Agent, laboratory or platform publish not just files, but the structured relationship between a Claim, the experiment that tested it, the execution that occurred, the evidence that was observed and the bounded assessment made from that evidence.

Claim → Experiment → Execution → Evidence → Assessment → Attestation

CAP is Agent-, model-, cloud- and Registry-neutral. A structurally valid CAP proves content identity and internal bindings. It does not prove that a signer is trusted, that an Assessment is correct, that a result was independently repeated or that a paper is true.

Record, Artifact and Bundle

CAP separates three concepts that older package-oriented formats often combine:

An Artifact might represent a research plan, a reproduction, a failed run, a new parameter experiment or an independent assessment. Once addressed by its digest, it is never modified. A retry or revision creates a new Artifact linked by derivedFrom, revises, reproduces, extends or another typed relation.

A Bundle may add signatures, current download locations, previews and public metadata without changing the underlying Artifact identity.

Bundle layout

The first CAP 1.0 Bundle transport remains a regular tar+gzip file:

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

The Artifact consists only of the canonical Manifest, declared Record bytes and declared embedded Blob bytes. Attestations, locations, projections and previews are Bundle attachments. A path locates bytes; it is never scientific identity.

Consumers must reject unsafe or duplicate paths, links, non-regular entries and undeclared files under records/ or blobs/.

Content identity

The stable Artifact identity is computed from exact RFC 8785 canonical Manifest bytes:

artifactDigest = SHA-256(JCS(cap-manifest.json))

The Manifest does not contain its own digest. A UUID may be a convenient label, but sha256:<digest> is the immutable address.

Every normative JSON Record is stored as RFC 8785 JSON Canonicalization Scheme bytes: I-JSON data, UTF-16 key ordering, ECMAScript primitive serialization, UTF-8 encoding, and no whitespace or trailing newline. See RFC 8785.

Scientific decimals use strings rather than binary floating-point values:

{
  "decimal": "81.900000",
  "unit": "percent"
}

Repacking the same Artifact, changing a preview, moving an external object or adding a detached signature leaves artifactDigest unchanged. Changing a root, Record, Blob descriptor or Artifact relation changes it.

Manifest and descriptors

cap-manifest.json declares the protocol version, Artifact creator, Profiles, roots, Record descriptors, Blob descriptors and immutable relations.

{
  "$schema": "https://citeark.com/schemas/cap/v1/manifest.schema.json",
  "mediaType": "application/vnd.citeark.cap.manifest.v1+json",
  "specVersion": "1.0.0-alpha.1",
  "artifact": {
    "id": "urn:uuid:artifact-01",
    "createdAt": "2026-08-24T10:30:00Z",
    "createdBy": {
      "ref": "urn:uuid:actor-assembler",
      "digest": "sha256:..."
    }
  },
  "profiles": [
    "https://citeark.com/cap/profiles/core/1.0",
    "https://citeark.com/cap/profiles/reproduction/1.0"
  ],
  "roots": [
    {
      "role": "primaryClaim",
      "ref": "urn:uuid:claim-01",
      "digest": "sha256:..."
    }
  ],
  "records": [],
  "blobs": [],
  "relations": []
}

A Record descriptor binds logical ID, semantic type, Schema, media type, size, digest and current Bundle path. Same-Artifact references may use the logical ID because the Manifest resolves it to one digest. Cross-Artifact references also bind the target Artifact digest, Record digest and Record type.

Blob descriptors use the same digest, size and media-type pattern. Availability is one of:

• embedded: the exact bytes are inside the Bundle;
• external: bytes are obtained separately and verified before use;
• withheld: sensitive or licensed bytes are intentionally unavailable, while their digest commitment and access policy remain portable.

Mutable download locations live in cap-locations.json, outside Artifact identity.

Scientific Records

CAP 1.0 defines seven scientific Record types plus Manifest and descriptor schemas:

Execution never contains reproduced: true. Process success is a runtime fact; Claim support belongs only in an Assessment.

Evidence records distinguish observed, declared, inferred and attested basis. A metric derived outside the Agent trust boundary identifies its parser, version, configuration, implementation digest when available and raw input Blob digests. This prevents an Agent's self-reported number from silently becoming verified evidence.

Assessment conclusions are deliberately limited to supports, challenges, contradicts and inconclusive. notAssessed is not a scientific conclusion; it is the absence of an Assessment and belongs in a Registry coverage view.

Independent reproduction is multidimensional. An Assessment records operator, implementation, environment, hardware and data independence separately.

Blinded execution and policy commitment

The execution Agent receives only Experiment.publicContract. That contract must not expose the paper-reported target, tolerance, acceptance criterion or private verification policy.

Before execution, the coordinator commits to the private policy using a high-entropy nonce:

policyCommitment = SHA-256(JCS({
  algorithm: "citeark-policy-commitment-v1",
  nonce: <at least 128 bits of entropy>,
  policy: <private comparison policy>
}))

The later Assessment reveals the policy and nonce. A verifier recomputes the commitment. This prevents post-outcome policy changes without making a low-entropy target enumerable from a salt-free hash.

A failed or partial execution is still a useful Artifact. If integrity fails or trustworthy Evidence is unavailable, the Assessment is inconclusive rather than an invented negative or positive result.

Agent Workflow 1.0

The CAP 1.0 reference Agent has one publication path:

Research Compiler
  → Research Plan CAP
  → blinded Execution Contract 1.0 + private policy commitment
  → isolated execution + Execution Result 1.0
  → out-of-sandbox evidence parsing, integrity checks and Assessment
  → Reproduction CAP --reproduces--> Research Plan Artifact Digest

Execution Result 1.0 may report only execution state, commands that actually ran, code changes, evidence files, scientific outputs and limitations. It may not contain verification or observedResult. Contract-selected deterministic parsers derive formal measurements from raw Evidence; an independent evaluator creates the scientific conclusion.

A low-level run directory is recovery and audit input, not an Artifact. The reference CLI exposes no pipeline replay command that can publish a CAP from an arbitrary research.json, private policy and run directory. Local pipeline execute creates both plan and reproduction .cap files. The platform path instead accepts only a plan digest that it has already verified and bound to the processing job. A missing reproduces relation, a target outside the verified plan, or a non-1.0 result envelope fails closed.

The complete pipeline records ten stages: research compilation, research-plan snapshot, execution contract, compute scheduling, autonomous reproduction, evidence parsing, verification, conclusion/card rendering, Artifact assembly and single-file packing. Internal checkpoints may restore execution but never cross the CAP trust boundary or become platform import sources.

Profiles

CAP Core stays small. Versioned Profiles add domain or publication constraints:

Future physical experiments, instruments, samples or mathematical proofs extend CAP through new Profiles rather than expanding Core for every discipline.

Trace without private chain-of-thought

The Agent Trace Profile stores observable NDJSON events with increasing sequence, eventType, occurredAt, observedAt, actor, execution, parent, inputs, outputs and attributes. Trace and span identifiers may use OpenTelemetry conventions.

CAP records prompts approved for publication, model and Agent identity, tool calls, commands, file changes, errors, retries and explicit structured decisions. It never requires hidden chain-of-thought.

Attestation and trust

CAP root attestations are detached. The preferred format is an in-toto Statement inside a DSSE envelope. The Statement subject is the Artifact SHA-256 and the CAP predicate identifies the actor and attestation role.

The reference implementation verifies Ed25519 keys offline. Public publishers may use Sigstore Bundles; institutions may use their own PKI or external key-resolution policy.

Verification reports these questions separately:

1. Is the Artifact structurally conformant?
2. Are declared Record and embedded Blob bytes intact?
3. Is a signature valid and bound to this Artifact?
4. Is the signer trusted for this purpose?
5. What bounded conclusion does an Assessment contain?
6. Has an independent actor published new Evidence or Assessment?

Co-signing identical bytes may add a detached Attestation. New evidence or a new scientific judgment creates a new Artifact that refers to the original.

Rights and interoperability

Rights attach to each source and Blob. A paper, repository, dataset, model and generated checkpoint may all have different terms. CAP does not grant redistribution rights and never lets one global license override those differences.

CAP reuses established standards as projections or envelopes:

• RO-Crate 1.3 for public research-object metadata;
• Workflow Run RO-Crate for existing workflow provenance;
• W3C PROV for Entity, Activity and Agent mappings;
• SPDX 3.0.1 for detailed software, model, dataset, build and rights inventories;
• in-toto and DSSE for authenticated metadata;
• OCI descriptor concepts for future Registry transport.

These projections never override canonical CAP Record contents or digests.

Pipeline and platform import

The CiteArk pipeline uses a two-layer CAP 1.0 snapshot chain. There is no platform-specific import bundle in between:

Research Compiler
  → Research Plan CAP
  → SourceWork / all Claims / planned Experiments / declared Evidence
  → trusted verification and research-plan import

each blinded reproduction target
  → Reproduction CAP --reproduces--> Research Plan Artifact Digest
  → Experiment / Execution / observed Evidence / Assessment

raw evidence + typed outputs
  → content-addressed Blobs + Evidence Records
private policy reveal + comparisons
  → Assessment Record
runner identity + processing binding
  → Actor Records + detached DSSE Attestation

A Research Plan CAP declares the research-plan/1.0 Profile. It contains no Execution or Assessment, and values reported by the paper have basis: declared. A planned Experiment may omit the private verification-policy commitment. Once scheduled, its Reproduction CAP must bind that commitment and reveal it in the Assessment. Every Reproduction CAP must use a Manifest reproduces relation to bind the imported Research Plan Artifact digest.

An internal Research Compiler checkpoint exists only for crash recovery. It has no CAP Artifact identity and cannot create repository, Claim or experiment projections. No pending signature or placeholder attestation crosses the trust boundary.

Small Blobs are embedded. Large Blobs are declared as external; the worker uploads them by digest before uploading the .cap Bundle. During import, the platform re-verifies the archive digest, Artifact Digest, every Record, embedded Blobs, policy commitment reveal, trusted Ed25519 DSSE signature and the attested jobId, repositoryId, source digest and base commit. A failure at any boundary prevents publication.

The platform first builds repository, Claim and planned-experiment projections from a verified Research Plan CAP. It then builds run, Evidence and Assessment projections from verified Reproduction CAPs whose plan relation matches. The importer also verifies that the exact Claim and Experiment versions in the reproduction are present and bound together in that plan; a correct parent digest alone cannot authorize an out-of-plan target. Files under projections/citeark/ and preview/ are presentation-only and are never authoritative import inputs. CAP 1.0 has no platform/import-bundle.json and no compatibility branch for an older manifest.

Verify and pack

The reference CLI processes CAP 1.0 only:

cd agent
node src/cli.mjs cap verify --dir ./artifact
node src/cli.mjs cap pack --dir ./artifact --output ./artifact.cap
node src/cli.mjs cap verify --file ./artifact.cap

A CAP 1.0 verifier safely extracts the Bundle, parses exact canonical Manifest bytes, computes artifactDigest, validates descriptors, checks every Record and embedded Blob, resolves references, applies supported Profiles, verifies policy reveals and finally checks detached Attestations.

Inputs without cap-manifest.json, with another specVersion, without the CAP 1.0 Manifest in the archive, or using the .citeark suffix are rejected. To bring an external paper, repository or dataset package into CAP, an importer creates a new CAP 1.0 Artifact with explicit source and transformation provenance; renaming the source bytes is not migration.

It reports structural conformance, materialization, signature validity, signer trust and scientific Assessment separately. A CLI valid exit status is never a truth score.

Reference materials in the CiteArk repository:

• agent/protocol/CAP.md — normative specification;
• agent/protocol/profiles/ — Profile rules;
• agent/protocol/MAPPINGS.md — standard mappings;
• agent/schemas/cap/v1/ — nine JSON Schemas;
• agent/protocol/conformance-v1.0-alpha.1.json — public vectors;
• agent/src/cap/v1/ — reference implementation.

The protocol, schemas and conformance vectors use CC0 1.0. That dedication does not alter the rights of scientific material referenced by a CAP Artifact.