types

type CanonicalChunk ¶

type CanonicalChunk struct {
	ID      string
	EntryID string
	Ordinal int
	// Revision is deprecated: graph revision is a mutation-concurrency token,
	// never a vector-freshness token (d-cpt-65i). Reconciliation and hit
	// validity ignore it. Retained only for source compatibility.
	Revision    string
	ContentHash string
	Text        string
	// The following persisted citation and identity fields carry everything a
	// store needs to render a citation and answer entry-presence queries
	// without re-deriving chunks. Both the CLI indexer and the application
	// vector search populate them through the shared chunk-derivation helper.
	Body                 string
	Breadcrumb           []string
	Depth                int
	IsSummary            bool
	IsAttachment         bool
	SourceAttachmentPath string
	// EntryHash is the entry-state hash (entry content + summary + attachment
	// bytes) — the same definition as the CLI manifest state hash.
	EntryHash string
}

type FocusWhen ¶

type FocusWhen struct {
	From string `yaml:"from,omitempty"`
	To   string `yaml:"to,omitempty"`
}

FocusWhen is the temporal scope for a focus or one of its involvement triples. At least one of From or To must be set when the field is present; the absent end means "open-ended in that direction." Dates are ISO YYYY-MM-DD format on disk and parsed into time.Time at validation time.

func (w *FocusWhen) IsZero() bool

func (w *FocusWhen) Validate() error

type GraphHealth ¶

type GraphHealth struct {
	Warnings   int
	LoadErrors int
	Issues     []HealthIssue
}

GraphHealth is a flat summary of graph-integrity problems: the count of entry warnings, the count of unreadable (load-failed) entries, and every problem as an ordered line (load failures first, then entry warnings).

func (h GraphHealth) Clean() bool

type HealthIssue ¶

type HealthIssue struct {
	Ref     string
	Message string
}

HealthIssue is one graph-integrity problem as a displayable line: the entry ID (or load ref) it concerns and the human message.

type IndexNamespace ¶

type IndexNamespace struct {
	Project     ProjectID
	Fingerprint string
	Metric      string
}

IndexNamespace keys one reconciled vector index. The fingerprint pins the embedding model (and thus the dimensionality), so dimensions are not part of the identity — stores enforce vector-length consistency per namespace at reconcile and query time instead.

type IndexSearchEntryCmd ¶

type IndexSearchEntryCmd struct {
	Entry       SearchEntryDescriptor
	OnPublished func(entryID string, chunks int)
}

type IndexedChunk ¶

type IndexedChunk struct {
	Chunk  CanonicalChunk
	Vector []float32
}

type Involvement ¶

type Involvement struct {
	Target string
	// Actors carries canonical-only names. Distinguishing "unset" (inherit
	// focus-level default) from "explicit empty" (deliberately
	// pull-available) requires the ActorsSet field; YAML's natural decoding
	// merges both into a nil slice, so we capture the distinction at
	// frontmatter parse time.
	Actors    []string
	ActorsSet bool
	When      *FocusWhen
}

Involvement is one entry in a kind: focus decision's involvement: list. Required: Target (entry ID this involvement is about). Optional: Actors (canonical-only; per-involvement override of focus-level default — explicit empty list means "deliberately unattributed / pull-available", distinct from the unset case which inherits the focus-level default). Optional: When (per-involvement temporal scope override).

type LintFinding ¶

type LintFinding struct {
	Category string
	Code     string
	Severity LintSeverity
	// EntryID names the entry (or file path, for load errors) the finding is
	// about; empty for store-level findings like index drift.
	EntryID string
	Message string
}

LintFinding is one categorized lint observation. Category names the provider that raised it (graph, index, procedure-runtime); Code names the specific check within it.

type LintQuery ¶

type LintQuery struct{}

LintQuery captures intent to surface graph integrity issues. Pure intent — the graph is held by the GraphFinder that runs the query.

type LintResult ¶

type LintResult struct {
	Findings []LintFinding
}

LintResult is the structured output of a LintQuery: categorized findings from every provider, in provider order. Presenters group by category; shells derive the exit code from Errors alone.

func (r *LintResult) Errors() int

type LintSeverity ¶

type LintSeverity string

LintSeverity classifies a lint finding's consequence: an error is a graph integrity problem and flips the exit code; an advisory records a risk the author may accept and never flips it (d-tac-rzi — an overshooting spec still runs; d-cpt-xc3 — spec-authoring advisories are never entry warnings).

const (
	LintError    LintSeverity = "error"
	LintAdvisory LintSeverity = "advisory"
)

type PartSize ¶

type PartSize struct {
	Part  string
	Bytes int
}

PartSize names one serve part and its byte size — the per-part accounting behind the serve-budget measurement (d-tac-qwc). Injects and lanes are the scaling parts; schema, diagnostics, and produced complete a serve's weight.

type PatchPair ¶

type PatchPair struct {
	Old string
	New string
}

PatchPair is one exact search-replace edit, applied by the staged-attachment edit path (internal/textpatch carries the apply semantics).

type ProjectID ¶

type ProjectID string

ProjectID identifies a project within a composition.

type ReconcileSearchIndexCmd ¶

type ReconcileSearchIndexCmd struct {
	// Callbacks run synchronously after persistence succeeds.
	OnEntryIndexed func(entryID string, chunkCount int)
	OnComplete     func(revision string, entriesIndexed, chunksStored int)
}

type ScoredChunkHit ¶

type ScoredChunkHit struct {
	Namespace IndexNamespace
	ChunkID   string
	EntryID   string
	// EntryHash is the version this hit belongs to, resolved by the store (row
	// metadata, or the manifest for a legacy row). Read-time filtering keeps
	// the hit only when it equals the current entry's state hash. Empty means
	// the store cannot report a version, so the hit is not version-filtered.
	EntryHash string
	// Revision is deprecated and ignored by hit validity (see CanonicalChunk).
	Revision    string
	ContentHash string
	Score       float64
	// Persisted citation fields, rendered directly into search citations so a
	// hit needs no re-derivation of its source chunk.
	Body                 string
	Breadcrumb           []string
	Depth                int
	IsSummary            bool
	IsAttachment         bool
	SourceAttachmentPath string
}

type SearchDiscoveryCursor ¶

type SearchDiscoveryCursor struct {
	Revision     string
	Namespace    IndexNamespace
	AfterEntryID string
	Selection    string
}

type SearchEntryDescriptor ¶

type SearchEntryDescriptor struct {
	Version        SearchEntryVersion
	SourceRevision string
}

SearchEntryDescriptor identifies exact retained input, including attachments. The host must retain SourceRevision until all work using it is finished.

type SearchEntryRequirement ¶

type SearchEntryRequirement struct {
	Entry     SearchEntryDescriptor
	Published bool
	Cursor    SearchDiscoveryCursor
}

type SearchEntryVersion ¶

type SearchEntryVersion struct {
	Namespace IndexNamespace
	EntryID   string
	EntryHash string
}

SearchEntryVersion is the publication and deduplication key. Revision is deliberately absent: identical content in different snapshots shares work.

type SearchSyncMode ¶

type SearchSyncMode string

const (
	SearchSyncNone  SearchSyncMode = "none"
	SearchSyncLocal SearchSyncMode = "local"
	SearchSyncAll   SearchSyncMode = "all"
)

func (m SearchSyncMode) Valid() bool

type ServeLane ¶

type ServeLane struct {
	Name string
	Text string
}

ServeLane is one rendered lane of a serve's instruction unit — the unit a host's served-once memory dedups at (d-tac-87o).

type ShowTreeBudget ¶

type ShowTreeBudget struct {
	MaxNodes    int
	MaxChildren int
}

ShowTreeBudget bounds a tree's expansion per direction: MaxNodes caps how many whole-entry nodes one direction may carry, MaxChildren caps one node's fan-out. Children past a bound land as TruncatedRefs — the same honest frontier the depth limit renders — never silently dropped. Zero values are unbounded: explicit pulls (sdd show, the MCP show tool) pass no budget and arrive complete (d-tac-rzi).

type StoredChunkRef ¶

type StoredChunkRef struct {
	ID string
	// Revision is deprecated and ignored by reconciliation (see CanonicalChunk).
	Revision    string
	ContentHash string
}

type StoredEntryRef ¶

type StoredEntryRef struct {
	EntryID string
	// EntryHash is the entry-state hash of this stored version — the same
	// definition as CanonicalChunk.EntryHash and the CLI manifest hash. Empty
	// only for a store that cannot report per-version identity.
	EntryHash string
}

StoredEntryRef identifies one stored (entry, version) pair in a persistent index. Presence is keyed by the pair: a store returns one ref per stored version of an entry, so a changed entry (a new EntryHash) reads as absent and is embedded as an added version rather than overwriting the old one.

type ViewBudget ¶

type ViewBudget struct {
	// GroupItems caps focus groups, participant groups, and WIP markers per
	// section.
	GroupItems int
	// RefsPerEntry caps expand(refs) sub-lines per entry.
	RefsPerEntry int
	// BodyBytes caps as-bodies sections: whole bodies while bytes fit.
	BodyBytes int
}

ViewBudget names the per-shape bounds a served view applies: every cut is at a whole unit (a focus group, a marker, a body, a ref sub-line) and the shape carries the dropped count plus a runnable pull for the remainder.

type Warning ¶

type Warning struct {
	Field   string // "refs", "closes", "supersedes"
	Value   string // the offending ID or value
	Message string // human-readable description
}

Warning represents a validation issue found on a graph entry.