Struct Document 

pub struct Document { /* private fields */ }

A Codex document.

Document provides a high-level interface for working with Codex documents, abstracting away the underlying archive structure.

Implementations

impl Document

pub fn academic_numbering(&self) -> Option<&NumberingConfig>

Get the academic numbering, if present.

pub fn academic_numbering_mut(&mut self) -> Result<Option<&mut NumberingConfig>>

Get a mutable reference to the academic numbering.

Errors

Returns an error if the document is in an immutable state.

pub fn has_academic_numbering(&self) -> bool

Check if the document has academic numbering.

pub fn set_academic_numbering(&mut self, value: NumberingConfig) -> Result<()>

Set the academic numbering.

Errors

Returns an error if the document is in an immutable state.

pub fn clear_academic_numbering(&mut self) -> Result<()>

Remove the academic numbering.

Errors

Returns an error if the document is in an immutable state.

pub fn comments(&self) -> Option<&CommentThread>

Get the comments, if present.

pub fn comments_mut(&mut self) -> Result<Option<&mut CommentThread>>

Get a mutable reference to the comments.

Errors

Returns an error if the document is in an immutable state.

pub fn has_comments(&self) -> bool

Check if the document has comments.

pub fn set_comments(&mut self, value: CommentThread) -> Result<()>

Set the comments.

Errors

Returns an error if the document is in an immutable state.

pub fn clear_comments(&mut self) -> Result<()>

Remove the comments.

Errors

Returns an error if the document is in an immutable state.

pub fn phantom_clusters(&self) -> Option<&PhantomClusters>

Get the phantom clusters, if present.

pub fn phantom_clusters_mut(&mut self) -> Result<Option<&mut PhantomClusters>>

Get a mutable reference to the phantom clusters.

Errors

Returns an error if the document is in an immutable state.

pub fn has_phantom_clusters(&self) -> bool

Check if the document has phantom clusters.

pub fn set_phantom_clusters(&mut self, value: PhantomClusters) -> Result<()>

Set the phantom clusters.

Errors

Returns an error if the document is in an immutable state.

pub fn clear_phantom_clusters(&mut self) -> Result<()>

Remove the phantom clusters.

Errors

Returns an error if the document is in an immutable state.

pub fn form_data(&self) -> Option<&FormData>

Get the form data, if present.

pub fn form_data_mut(&mut self) -> Result<Option<&mut FormData>>

Get a mutable reference to the form data.

Errors

Returns an error if the document is in an immutable state.

pub fn has_form_data(&self) -> bool

Check if the document has form data.

pub fn set_form_data(&mut self, value: FormData) -> Result<()>

Set the form data.

Errors

Returns an error if the document is in an immutable state.

pub fn clear_form_data(&mut self) -> Result<()>

Remove the form data.

Errors

Returns an error if the document is in an immutable state.

pub fn bibliography(&self) -> Option<&Bibliography>

Get the bibliography, if present.

pub fn bibliography_mut(&mut self) -> Result<Option<&mut Bibliography>>

Get a mutable reference to the bibliography.

Errors

Returns an error if the document is in an immutable state.

pub fn has_bibliography(&self) -> bool

Check if the document has bibliography.

pub fn set_bibliography(&mut self, value: Bibliography) -> Result<()>

Set the bibliography.

Errors

Returns an error if the document is in an immutable state.

pub fn clear_bibliography(&mut self) -> Result<()>

Remove the bibliography.

Errors

Returns an error if the document is in an immutable state.

pub fn jsonld_metadata(&self) -> Option<&JsonLdMetadata>

Get the JSON-LD metadata, if present.

pub fn jsonld_metadata_mut(&mut self) -> Result<Option<&mut JsonLdMetadata>>

Get a mutable reference to the JSON-LD metadata.

Errors

Returns an error if the document is in an immutable state.

pub fn has_jsonld_metadata(&self) -> bool

Check if the document has JSON-LD metadata.

pub fn set_jsonld_metadata(&mut self, value: JsonLdMetadata) -> Result<()>

Set the JSON-LD metadata.

Errors

Returns an error if the document is in an immutable state.

pub fn clear_jsonld_metadata(&mut self) -> Result<()>

Remove the JSON-LD metadata.

Errors

Returns an error if the document is in an immutable state.

impl Document

pub fn open<P: AsRef<Path>>(path: P) -> Result<Self>

Open a document from a file path.

Errors

Returns an error if:

• The file cannot be opened
• The archive is invalid
• Required files are missing or malformed

pub fn open_from_reader<R: Read + Seek>(reader: R) -> Result<Self>

Open a document from any Read + Seek source.

Errors

Returns an error if:

• The source is not a valid Codex archive
• Required files are missing or malformed

pub fn from_bytes(data: Vec<u8>) -> Result<Self>

Open a document from bytes.

Errors

Returns an error if the data is not a valid Codex document.

pub fn save<P: AsRef<Path>>(&self, path: P) -> Result<()>

Save the document to a file.

Errors

Returns an error if:

• The file cannot be created
• Writing fails

pub fn write_to<W: Write + Seek>(&self, writer: W) -> Result<()>

Write the document to any Write + Seek destination.

Errors

Returns an error if writing fails.

pub fn to_bytes(&self) -> Result<Vec<u8>>

Write the document to bytes.

Errors

Returns an error if serialization fails.

impl Document

pub fn block_index(&self) -> Result<BlockIndex>

Generate a block index for this document.

The block index contains hashes for all content blocks and the Merkle root. This is used for generating proofs and verifying content integrity.

Errors

Returns an error if the content has no blocks.

pub fn prove_block(&self, block_index: usize) -> Result<BlockProof>

Generate a Merkle proof for a specific block by index.

The proof can be used to verify that a block is part of this document without revealing the entire document content.

Arguments

• block_index - The zero-based index of the block to prove

Errors

Returns an error if:

• The content has no blocks
• The block index is out of bounds

pub fn prove_block_by_id(&self, block_id: &str) -> Result<BlockProof>

Generate a Merkle proof for a block by its ID.

Arguments

• block_id - The ID of the block to prove

Errors

Returns an error if:

• The content has no blocks
• No block with the given ID exists

pub fn verify_proof(&self, proof: &BlockProof, block_hash: &DocumentId) -> bool

Verify a block proof against this document.

Arguments

• proof - The proof to verify
• block_hash - The hash of the block being verified

Returns

true if the proof is valid and the block is part of this document.

pub fn merkle_root(&self) -> Result<DocumentId>

Get the Merkle root hash for this document’s content.

Errors

Returns an error if the content has no blocks.

pub fn provenance_record(&self) -> Result<ProvenanceRecord>

Create a provenance record for this document.

Errors

Returns an error if computing the document ID or Merkle root fails.

impl Document

pub fn signature_file(&self) -> Option<&SignatureFile>

Available on crate feature signatures only.

Get a reference to the signature file, if present.

pub fn signatures(&self) -> &[Signature]

Available on crate feature signatures only.

Get the signatures from the document.

pub fn add_signature(&mut self, signature: Signature) -> Result<()>

Available on crate feature signatures only.

Add a signature to the document.

This adds the signature to the document’s signature file. If no signature file exists, one will be created. The document ID in the signature file will be updated to match the current computed document ID.

Errors

Returns an error if the document ID cannot be computed.

pub fn has_signatures(&self) -> bool

Available on crate feature signatures only.

Check if the document has any signatures.

pub fn encryption_metadata(&self) -> Option<&EncryptionMetadata>

Available on crate feature encryption only.

Get a reference to the encryption metadata, if present.

pub fn is_encrypted(&self) -> bool

Available on crate feature encryption only.

Check if the document has encryption metadata.

pub fn set_encryption(&mut self, metadata: EncryptionMetadata) -> Result<()>

Available on crate feature encryption only.

Set encryption metadata for this document.

Errors

Returns an error if the document is in an immutable state.

pub fn clear_encryption(&mut self) -> Result<()>

Available on crate feature encryption only.

Remove encryption metadata from this document.

Errors

Returns an error if the document is in an immutable state.

impl Document

pub fn submit_for_review(&mut self) -> Result<()>

Submit the document for review.

Transitions from draft to review state. This computes the document ID and stores it in the manifest.

Errors

Returns an error if:

• The document is not in draft state
• Computing the document ID fails

pub fn freeze(&mut self) -> Result<()>

Freeze the document.

Transitions from review to frozen state. This requires:

• At least one signature
• Lineage information (parent reference or explicit root)
• At least one precise layout (for visual reproduction)

Errors

Returns an error if:

• The document is not in review state
• No signatures are present
• No lineage is set
• No precise layout is present

pub fn publish(&mut self) -> Result<()>

Publish the document.

Transitions from frozen to published state.

Errors

Returns an error if the document is not in frozen state.

pub fn revert_to_draft(&mut self) -> Result<()>

Revert the document to draft state.

Transitions from review back to draft state. This is only allowed if the document has no signatures (to prevent removing signed content).

Errors

Returns an error if:

• The document is not in review state
• The document has signatures

pub fn fork(&self) -> Result<Document>

Fork the document to create a new draft with lineage.

Creates a new document in draft state that references this document as its parent in the lineage chain. The forked document:

• Has a new (pending) document ID
• Is in draft state
• Has lineage pointing to this document with ancestor chain
• Has incremented version number and depth
• Has no signatures

Errors

Returns an error if computing the document ID fails.

pub fn set_lineage( &mut self, parent: Option<DocumentId>, version: u32, note: Option<String>, ) -> Result<()>

Set lineage information for this document.

This is used to establish lineage before freezing a document. For the first version of a document, call with None as parent to create a root lineage entry.

Errors

Returns an error if the document is in an immutable state.

impl Document

pub fn compute_id(&self) -> Result<DocumentId>

Compute the document ID from content and identity metadata.

Per spec §06 §4.1, the document ID is computed by hashing the canonicalized semantic identity of the document. This includes:

• Content blocks (the document’s structural content)
• Identity metadata: title, creator, subject, description, language

The hash explicitly excludes presentation layers, signatures, phantom data, form data, and collaboration data — these are non-identity concerns with their own integrity mechanisms.

Errors

Returns an error if canonicalization fails.

pub fn verify(&self) -> Result<VerificationReport>

Verify the document integrity.

This checks:

• Content hash matches manifest
• Document ID is valid (if not pending)

Errors

Returns an error if verification fails.

pub fn validate_extensions(&self) -> ExtensionValidationReport

Validate extension declarations.

This checks that all extension namespaces used in the document’s content (blocks and marks) are declared in the manifest’s extensions list.

Returns

An ExtensionValidationReport containing:

• List of used extension namespaces
• List of declared extension namespaces
• List of undeclared (used but not declared) namespaces
• Warnings for any issues found

impl Document

pub fn builder() -> DocumentBuilder

Create a new document builder.

pub fn manifest(&self) -> &Manifest

Get a reference to the manifest.

pub fn content(&self) -> &Content

Get a reference to the content.

pub fn content_mut(&mut self) -> Result<&mut Content>

Get a mutable reference to the content.

Errors

Returns an error if the document is in an immutable state.

pub fn dublin_core(&self) -> &DublinCore

Get a reference to the Dublin Core metadata.

pub fn dublin_core_mut(&mut self) -> Result<&mut DublinCore>

Get a mutable reference to the Dublin Core metadata.

Errors

Returns an error if the document is in an immutable state.

pub fn title(&self) -> &str

Get the document title.

pub fn creators(&self) -> Vec<&str>

Get the document creators.

pub fn state(&self) -> DocumentState

Get the document state.

pub fn id(&self) -> &DocumentId

Get the document ID.

pub fn hash_algorithm(&self) -> HashAlgorithm

Get the hash algorithm used.

pub fn manifest_mut(&mut self) -> &mut Manifest

Get a mutable reference to the manifest for advanced modifications.

Use with caution - this bypasses state machine validation.

Trait Implementations

impl Clone for Document

fn clone(&self) -> Document

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Document

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.