source

Documentation

Index

• func CloneMetadata(metadata map[string]any) (map[string]any, error)
• func DigestChunk(chunk Chunk) (string, error)
• func DigestChunkPlan(plan ChunkPlan) (string, error)
• func DigestDocument(doc *SourceDocument) (string, error)
• func UnitIndex(doc *SourceDocument, unitID int) (int, bool)
• func ValidateChunkAnnotations(annotations ChunkAnnotations) error
• func ValidateChunkPlan(doc *SourceDocument, plan ChunkPlan) error
• func ValidateDocument(doc *SourceDocument) error
• func ValidateRef(doc *SourceDocument, ref SourceRef) error
• type Chunk
  • func MaterializeChunkPlan(doc *SourceDocument, plan ChunkPlan) ([]Chunk, error)
• type ChunkAnnotations
  • func CanonicalizeChunkAnnotations(annotations ChunkAnnotations) (ChunkAnnotations, error)
  • func CloneChunkAnnotations(annotations ChunkAnnotations) ChunkAnnotations
• type ChunkPlan
  • func CanonicalizeChunkPlan(plan ChunkPlan) (ChunkPlan, error)
  • func CloneChunkPlan(plan ChunkPlan) ChunkPlan
• type ChunkRange
• type DocumentIndex
  • func NewDocumentIndex(doc *SourceDocument) DocumentIndex
  • func (i DocumentIndex) DocumentID() (string, bool)
  • func (i DocumentIndex) Position(unitID int) (int, bool)
  • func (i DocumentIndex) ValidateRef(ref SourceRef) error
• type SourceDocument
• type SourceRef
• type SourceUnit

Functions

func CloneMetadata

func CloneMetadata(metadata map[string]any) (map[string]any, error)

CloneMetadata returns an independently owned copy of JSON-shaped metadata. It preserves concrete map, slice, and array types while rejecting values that cannot be safely represented as JSON-shaped metadata.

func DigestChunk

func DigestChunk(chunk Chunk) (string, error)

DigestChunk returns a deterministic digest of a chunk, including its source provenance, content, units, and metadata.

func DigestChunkPlan

func DigestChunkPlan(plan ChunkPlan) (string, error)

DigestChunkPlan returns a deterministic digest of the logical plan. Storage schema, producer provenance, warnings, and timestamps are intentionally not part of the digest.

func DigestDocument

func DigestDocument(doc *SourceDocument) (string, error)

DigestDocument returns a deterministic digest of the canonical source document content. The existing Digest field is excluded from its own digest.

func UnitIndex

func UnitIndex(doc *SourceDocument, unitID int) (int, bool)

func ValidateChunkAnnotations

func ValidateChunkAnnotations(annotations ChunkAnnotations) error

ValidateChunkAnnotations requires annotations to already contain canonical JSON. CanonicalizeChunkAnnotations can be used at producer boundaries.

func ValidateChunkPlan

func ValidateChunkPlan(doc *SourceDocument, plan ChunkPlan) error

ValidateChunkPlan validates a canonical plan against the current source. Ranges may contain gaps or overlap, but their start positions must increase.

func ValidateDocument

func ValidateDocument(doc *SourceDocument) error

func ValidateRef

func ValidateRef(doc *SourceDocument, ref SourceRef) error

Types

type Chunk

type Chunk struct {
	ID              string           `json:"id"`
	SourceID        string           `json:"source_id"`
	Index           int              `json:"index"`
	Ref             SourceRef        `json:"ref"`
	Content         []byte           `json:"-"`
	MediaType       string           `json:"media_type"`
	Units           []SourceUnit     `json:"units"`
	Metadata        map[string]any   `json:"metadata,omitempty"`
	Annotations     ChunkAnnotations `json:"annotations,omitempty"`
	PlanAnnotations ChunkAnnotations `json:"plan_annotations,omitempty"`
}

func MaterializeChunkPlan

func MaterializeChunkPlan(doc *SourceDocument, plan ChunkPlan) ([]Chunk, error)

MaterializeChunkPlan deterministically expands a validated plan into chunks.

type ChunkAnnotations

type ChunkAnnotations map[string]json.RawMessage

func CanonicalizeChunkAnnotations

func CanonicalizeChunkAnnotations(annotations ChunkAnnotations) (ChunkAnnotations, error)

CanonicalizeChunkAnnotations validates annotation namespaces and JSON values and returns an independently owned map whose values use canonical JSON bytes.

func CloneChunkAnnotations

func CloneChunkAnnotations(annotations ChunkAnnotations) ChunkAnnotations

CloneChunkAnnotations returns a deep clone, including every raw JSON value.

type ChunkPlan

type ChunkPlan struct {
	SourceDigest string           `json:"source_digest"`
	Ranges       []ChunkRange     `json:"ranges"`
	Annotations  ChunkAnnotations `json:"annotations,omitempty"`
}

func CanonicalizeChunkPlan

func CanonicalizeChunkPlan(plan ChunkPlan) (ChunkPlan, error)

CanonicalizeChunkPlan returns a deep clone with canonical annotation bytes.

func CloneChunkPlan

func CloneChunkPlan(plan ChunkPlan) ChunkPlan

CloneChunkPlan returns a deep clone of a chunk plan.

type ChunkRange

type ChunkRange struct {
	StartUnitID int              `json:"start_unit_id"`
	EndUnitID   int              `json:"end_unit_id"`
	Annotations ChunkAnnotations `json:"annotations,omitempty"`
}

type DocumentIndex

type DocumentIndex struct {
	// contains filtered or unexported fields
}

DocumentIndex is an immutable snapshot of a source document's identity and unit positions for repeated source-reference operations.

func NewDocumentIndex

func NewDocumentIndex(doc *SourceDocument) DocumentIndex

NewDocumentIndex snapshots doc without retaining or mutating it.

func (DocumentIndex) DocumentID

func (i DocumentIndex) DocumentID() (string, bool)

DocumentID returns the indexed document identity.

func (DocumentIndex) Position

func (i DocumentIndex) Position(unitID int) (int, bool)

Position returns the indexed document position for unitID.

func (DocumentIndex) ValidateRef

func (i DocumentIndex) ValidateRef(ref SourceRef) error

ValidateRef validates ref against the indexed document snapshot.

type SourceDocument

type SourceDocument struct {
	ID       string         `json:"id"`
	Kind     string         `json:"kind"`
	Format   string         `json:"format"`
	Digest   string         `json:"digest"`
	Units    []SourceUnit   `json:"units"`
	Metadata map[string]any `json:"metadata,omitempty"`
}

type SourceRef

type SourceRef struct {
	SourceID    string `json:"source_id"`
	StartUnitID int    `json:"start_unit_id"`
	EndUnitID   int    `json:"end_unit_id"`
}

type SourceUnit

type SourceUnit struct {
	ID       int            `json:"id"`
	Kind     string         `json:"kind"`
	Text     string         `json:"text"`
	Ref      SourceRef      `json:"ref"`
	Metadata map[string]any `json:"metadata,omitempty"`
}