query

type Citation ¶ added in v0.4.0

type Citation struct {
	Breadcrumb           []string
	Snippet              string
	SourceAttachmentPath string
	IsSummary            bool
	IsAttachment         bool
	Score                float32
}

Citation describes the chunk that motivated the hit — used to render the user-facing snippet so callers understand source. Breadcrumb is the heading-chain (empty for pre-heading body or summary chunks). Snippet is the citation body (~150 chars) with no Entry/Breadcrumb preamble.

Score is the per-chunk score the finder computed (depth/summary adjusted, status-adjusted at entry level). Different citations from the same entry typically carry different scores — the presenter normalizes them to a relative percentage at render time so the reader sees both the strongest hit and how the weaker ones compare.

type ConfigEntry ¶ added in v0.15.0

type ConfigEntry struct {
	Key    string
	Value  string
	Source string
	Secret bool
}

ConfigEntry is one row of the effective-config view. Secret entries carry a masked Value on every surface.

type EffectiveConfigQuery ¶ added in v0.15.0

type EffectiveConfigQuery struct {
	SDDDir string
	// Key restricts the result to one dotted key (e.g. "llm.model").
	// Empty returns every effective entry.
	Key string
}

EffectiveConfigQuery asks for the fully resolved config overlay with per-value provenance: which layer — global, project (committed), local, or a baked default — supplied each effective value. SDDDir empty means the caller is outside an sdd repo: global settings and defaults only.

type EffectiveConfigResult ¶ added in v0.15.0

type EffectiveConfigResult struct {
	Entries []ConfigEntry
}

EffectiveConfigResult carries the resolved entries in schema order.

type Finding ¶

type Finding struct {
	Severity    Severity
	Category    string
	Observation string
}

Finding is a single observation from pre-flight validation.

type IndexLintQuery ¶ added in v0.15.0

type IndexLintQuery struct {
	Embedding model.EmbeddingConfig
	IndexDir  string
}

IndexLintQuery captures intent to surface search-index health: the resolved embedding config (flag/config merging is the shell's job) and the local index location. Processed by Finder.IndexLint into the index-side fields of a LintResult.

type InfoQuery ¶ added in v0.5.2

type InfoQuery struct{}

InfoQuery captures intent to read session framing — participant identity, search capability, and configured graph language. No fields today; declared as a struct so the surface evolves consistently with the rest of the CQRS layer.

type InfoResult ¶ added in v0.5.2

type InfoResult struct {
	LocalParticipant string
	Language         string
	Search           string
}

InfoResult is the structured snapshot of session framing.

LocalParticipant surfaces the canonical participant name from .sdd/config.local.yaml so agents reading the header see ground truth without inferring from entries (which may carry drift). Empty means "not configured".

Language surfaces the configured graph language (locale code) from .sdd/config.yaml so the /sdd skill knows whether to load a translation vocabulary and author entries in the configured language. Empty means English (default) — the line is suppressed at render time.

Search renders as `text` when only text mode is available and `vector,text` when an embedding provider is configured.

type LintQuery ¶

type LintQuery struct {
	Graph *model.Graph
}

LintQuery captures intent to surface graph integrity issues.

type LintResult ¶

type LintResult struct {
	Entries     []*model.Entry
	TotalIssues int

	// IndexConfigured is true when an embedding provider is configured.
	// When false, the rest of the index-side fields are zero values and
	// presenters skip rendering the index section.
	IndexConfigured bool
	// IndexEntryCount is the number of entries the manifest knows about.
	IndexEntryCount int
	// IndexDriftCount is the number of manifest entries whose recorded
	// fingerprint differs from the configured embedder. Run
	// `sdd index --force` (or just `sdd search` to lazy-fill) to
	// converge.
	IndexDriftCount int
	// IndexFingerprint is the current embedder fingerprint, included in
	// the lint output so the user can see what the index is being
	// compared against.
	IndexFingerprint string

	// RepoIndexDrift lists connected repos whose cache index holds entries
	// embedded under a fingerprint other than the shared (global) embedder.
	// A drifted repo re-embeds on the next cross-graph search; lint
	// surfaces it so the cost isn't a surprise. Populated by the CLI lint
	// action alongside the local index fields.
	RepoIndexDrift []RepoIndexDriftInfo
}

LintResult is the structured output of a LintQuery: every entry that has at least one warning, plus the total warning count for convenience.

Index-side fields (IndexConfigured, IndexEntryCount, IndexDriftCount, IndexFingerprint, RepoIndexDrift) are populated by Finder.IndexLint when an embedding provider is configured. They surface the search index's health alongside graph health so a single `sdd lint` run reports both.

type PreflightQuery ¶

type PreflightQuery struct {
	Entry   *model.Entry
	Graph   *model.Graph
	Model   string        // LLM model identifier (e.g. "claude-sonnet-4-6")
	Timeout time.Duration // hard timeout for the validator call
}

PreflightQuery captures intent to validate an entry against the graph using the pre-flight LLM validator. Pure read — no side effects of its own; the runner dependency injected into the finder handles the LLM call.

type PreflightResult ¶

type PreflightResult struct {
	Findings []Finding
}

PreflightResult holds all findings from a pre-flight validator run. An empty Findings slice means the validator reported no findings.

func (r *PreflightResult) HasBlocking() bool

type ReadAttachmentQuery ¶ added in v0.14.0

type ReadAttachmentQuery struct {
	Graph    *model.Graph
	GraphDir string
	// EntryID is the full ID of the entry whose attachment is read.
	EntryID string
	// Name selects the attachment by filename. Optional when the entry has
	// exactly one attachment.
	Name string
	// Offset is the byte position to start reading from (0 = start).
	Offset int64
	// MaxBytes caps the returned content size. Zero applies the default page
	// size.
	MaxBytes int
}

ReadAttachmentQuery captures intent to read an entry's attachment content through the CLI-owned accessor, so agents never derive storage paths themselves (20260606-004059-d-tac-d21). Content is paged for remote consumers: Offset is a byte position into the file, MaxBytes caps the returned slice.

type ReadAttachmentResult ¶ added in v0.14.0

type ReadAttachmentResult struct {
	EntryID string
	// Name is the resolved attachment filename.
	Name string
	// Content is the page read, as UTF-8 text.
	Content string
	// Offset echoes the byte position the page started at.
	Offset int64
	// NextOffset is the byte position to pass for the following page; only
	// meaningful when More is true.
	NextOffset int64
	// TotalBytes is the attachment's full size.
	TotalBytes int64
	// More reports whether content remains past this page.
	More bool
	// Available lists the entry's attachment filenames — the discoverable
	// surface when Name was ambiguous or the caller wants the inventory.
	Available []string
	// Path is the attachment's absolute filesystem path. The accessor always
	// resolves it; consumers decide whether to expose it (the MCP tool hands
	// it out only to local clients, which can then read the file directly
	// instead of paging).
	Path string
}

ReadAttachmentResult is one page of attachment content plus the paging state a caller needs to continue.

type RepoIndexDriftInfo ¶ added in v0.15.0

type RepoIndexDriftInfo struct {
	RepoID     string
	DriftCount int
	EntryCount int
}

RepoIndexDriftInfo names one connected repo's index drift.

type SchemaStatusQuery ¶ added in v0.2.0

type SchemaStatusQuery struct {
	// SDDDir is the absolute path to the .sdd/ directory. The query resolves
	// meta.json relative to this path.
	SDDDir string

	// BinaryVersion is the running sdd binary's version string (semver for
	// releases, "dev" or similar for local builds). Dev builds bypass both
	// compatibility gates.
	BinaryVersion string

	// BinarySchemaVersion is the schema version the binary understands. The
	// call site passes model.CurrentGraphSchemaVersion.
	BinarySchemaVersion int
}

SchemaStatusQuery captures intent to evaluate the current binary against the graph's .sdd/meta.json compatibility fields.

The dispatcher-level write-gate runs this query before any command that mutates the graph; read commands bypass the query entirely.

type SchemaStatusResult ¶ added in v0.2.0

type SchemaStatusResult struct {
	// MetaExists is false when .sdd/meta.json is not present on disk. In
	// that case Meta is nil and Compatibility is considered compatible (an
	// uninitialized graph will be set up on the next init).
	MetaExists bool

	// Meta is the parsed contents of .sdd/meta.json when MetaExists is true.
	Meta *model.SchemaMeta

	// Compatibility is the result of checking Meta against the binary's
	// version and schema version. Always populated (with Compatible = true)
	// when MetaExists is false.
	Compatibility model.CompatibilityResult
}

SchemaStatusResult reports whether the binary is permitted to proceed and, when !Compatibility.Compatible, why.

type SearchEntry ¶ added in v0.4.0

type SearchEntry struct {
	Entry     *model.Entry
	Score     float32
	Citations []Citation
	// RepoID names the connected repo a cross-graph hit came from; empty
	// for local hits. Presenters render remote IDs with this prefix.
	RepoID string
}

SearchEntry pairs a graph entry with its score and one-or-more citations. The citation slice is ordered best-first; for entries with multiple strongly-matching chunks (e.g. a long plan whose summary, approach section, and attachment all match a query) the slice carries each one so the agent reading the result sees the breadth of why the entry matched, not just its single strongest chunk.

func (e SearchEntry) Citation() Citation

func (e SearchEntry) DisplayID() string

type SearchMode ¶ added in v0.4.0

type SearchMode string

SearchMode is derived from the SearchQuery's input shape: text-only, vector-only, or hybrid (when both --term and --query are supplied). Stored as a string so presenters and skill guidance can render it without importing the query package.

const (
	SearchModeText   SearchMode = "text"
	SearchModeVector SearchMode = "vector"
	SearchModeHybrid SearchMode = "hybrid"
)

type SearchQuery ¶ added in v0.4.0

type SearchQuery struct {
	// Graph is the loaded graph used for filtering and entry resolution.
	// Required.
	Graph *model.Graph

	// Terms are the --term values: regex strings combined with AND. Each
	// must match somewhere in the entry's searchable text. Empty disables
	// text mode.
	Terms []string

	// Phrase is the --query value: a free-form phrase used for vector
	// search. Empty disables vector mode.
	Phrase string

	// Filter is the type/layer/kind filter (model.GraphFilter), the same
	// filter shape the view pipeline composes.
	Filter model.GraphFilter

	// IncludeSuperseded includes entries whose derived status is
	// superseded-by-something. Default false — superseded entries are
	// excluded so search seeds reflect the current shape of the graph.
	IncludeSuperseded bool

	// Limit caps the number of returned entries. Zero means
	// DefaultSearchLimit.
	Limit int

	// MaxCitationsPerEntry is the literal cap on citations a single entry
	// may contribute. The value is taken as-is: 0 suppresses citations
	// entirely (entry headers only — the mechanical "which entries match,
	// and what topics do they carry" lookup), 1 renders one line per entry,
	// higher surfaces more of the matching surface. Unlike EffectiveLimit's
	// zero-means-default rule, zero here means zero — the default is applied
	// at the CLI boundary via cmd.IsSet, so the struct field carries literal
	// intent and programmatic callers must set the cap they want.
	MaxCitationsPerEntry int

	// Repos selects connected repos to search in addition to the local
	// graph (additive, repeatable at the CLI as --repo). AllRepos selects
	// every connected repo. The orchestration layer resolves the selection
	// into per-repo search members; these fields carry the caller's intent.
	Repos    []string
	AllRepos bool
}

SearchQuery carries the parsed input for the sdd search command. The finder derives the mode from which fields are populated.

func (q SearchQuery) EffectiveLimit() int

func (q SearchQuery) EffectiveMaxCitations() int

func (q SearchQuery) Mode() SearchMode

type SearchResult ¶ added in v0.4.0

type SearchResult struct {
	Mode    SearchMode
	Entries []SearchEntry
}

SearchResult carries the top-N entries with citations for rendering.

type SectionResult ¶ added in v0.5.0

type SectionResult struct {
	Render string            // render function name (e.g. "as-list")
	Name   string            // section header set by `name(string)`; empty = no header
	Data   model.SectionData // shape-tagged data variant produced by the finder
	// Brief switches entry-line rendering to the compact form: identity
	// qualifiers plus the first summary sentence, no attribute segments.
	Brief bool
}

SectionResult is one section's render-ready data plus dispatch metadata. Render names the presenter that should consume Data; Data carries the shape-tagged result. The presenter validates that Data.Shape() matches what Render expects before rendering.

Name carries the section header set by `name(string)`. Empty Name means the section renders without a `## <title>` header (the slice 5/6 default for as-list and as-grouped).

type Severity ¶

type Severity string

Severity classifies a pre-flight finding. The tooling layer decides what to block on (currently: only SeverityHigh blocks); templates describe severity in purely semantic terms and never name a threshold.

const (
	SeverityHigh   Severity = "high"
	SeverityMedium Severity = "medium"
	SeverityLow    Severity = "low"
)

type ShowGroup ¶

type ShowGroup struct {
	Primary *model.Entry
	// PrimaryID is the display identity — repo-prefixed
	// (<repo-id>:<entry-id>) when the primary lives in a connected repo's
	// graph, bare otherwise.
	PrimaryID            string
	PrimaryStatus        model.Status
	PrimarySupersedePath []string
	PrimaryTopics        []model.TopicPath
	Upstream             []model.ShowTreeItem
	Downstream           []model.ShowTreeItem
}

ShowGroup is one primary's full tree: the primary entry, its upstream chain, and its downstream chain. Primary-derived attributes (status, supersede trail, effective topics) are carried alongside so presenters render without touching the graph. Multiple groups are joined with separators.

type ShowQuery ¶

type ShowQuery struct {
	Graph     *model.Graph
	IDs       []string
	UpDepth   int // upstream expansion depth (grounding chain); 0 = no upstream
	DownDepth int // downstream expansion depth (consumers); 0 = no downstream
}

ShowQuery captures intent to render a set of entries with their reference chains. Upstream and downstream each expand to their own depth; a depth of 0 skips that direction (downstream off, or upstream off, or both → primary only).

type ShowResult ¶

type ShowResult struct {
	Graph  *model.Graph // needed to render derived attributes like status
	Groups []ShowGroup
}

ShowResult is the structured output for a ShowQuery — one group per primary.

type SkillStatusEntry ¶ added in v0.2.0

type SkillStatusEntry struct {
	Skill    string
	RelPath  string
	AbsPath  string
	Status   model.SkillInstallStatus
	Embedded model.SkillBundleEntry
	// Installed is the parsed on-disk copy. Nil when Status = Missing.
	Installed *model.SkillFile
}

SkillStatusEntry carries the inputs a handler needs to decide whether (and how) to write the file: the embedded source, the parsed on-disk copy (nil if missing), and the computed status classification.

type SkillStatusQuery ¶ added in v0.2.0

type SkillStatusQuery struct {
	Target   model.AgentTarget
	Scope    model.Scope
	RepoRoot string // required for ScopeProject
	UserHome string // required for ScopeUser
}

SkillStatusQuery captures intent to read the install state of the embedded skill bundle against a target agent's skill directory.

type SkillStatusResult ¶ added in v0.2.0

type SkillStatusResult struct {
	// InstallDir is the resolved absolute directory where skills install
	// for this target + scope combination.
	InstallDir string

	// Entries is one row per embedded skill file.
	Entries []SkillStatusEntry
}

SkillStatusResult is a per-entry snapshot of the bundle compared to disk.

type StatsQuery ¶ added in v0.9.0

type StatsQuery struct {
	StatsDir string
	Since    *time.Time
	Until    time.Time
	Op       string
	Provider string
	Model    string
}

StatsQuery captures intent to read and aggregate the local LLM/embedding stats sink. A nil Since means all-time; empty Op/Provider/Model strings mean no constraint on that field. Until is the reference "now" used for the range's upper bound in rendering.

type StatsResult ¶ added in v0.9.0

type StatsResult struct {
	Report    model.StatsReport
	Source    string
	Since     *time.Time
	Until     time.Time
	SinkEmpty bool
}

StatsResult is the aggregated output of a StatsQuery. SinkEmpty distinguishes "no sink on disk yet" from "sink had records but the filter excluded them all", so the renderer can phrase the empty case correctly.

type SyncStatusQuery ¶ added in v0.3.0

type SyncStatusQuery struct {
	// SDDDir is the .sdd/ directory where the last-fetch marker lives.
	SDDDir string
	// RespectCooldown, when true, short-circuits the query with a Skipped
	// state if the last fetch is within the configured cooldown window.
	// When false the fetch runs regardless — useful for callers invoked
	// by an explicit user action rather than incidental to a command.
	RespectCooldown bool
}

SyncStatusQuery captures intent to check whether the local graph is in sync with the upstream branch. Processing involves a (potentially rate-limited) git fetch and several read-only git plumbing calls; the side effect of touching the last-fetch marker is considered internal bookkeeping rather than a domain mutation, matching the PreflightQuery precedent where an LLM call is embedded in a read-intent query.

type ViewQuery ¶ added in v0.5.0

type ViewQuery struct {
	Graph    *model.Graph
	Layout   model.Layout
	GraphDir string
}

ViewQuery captures intent to execute a layout pipeline against the graph. The Layout AST is produced upstream by ParseLayout — the finder consumes the parsed shape rather than the raw `--layout` string.

GraphDir lets the finder source from disk when a section uses `source(wip)` — the executor calls LoadWIPMarkers against this directory rather than receiving pre-resolved markers in the query slot. Mirrors the shape used by WIPListQuery; can be left empty when no section needs it (the executor errors at section-evaluation time if source(wip) appears without a configured GraphDir). The broader CQRS leak across read queries is captured separately in s-tac-m09 — slice 8 follows the existing peer shape rather than diverging.

type ViewResult ¶ added in v0.5.0

type ViewResult struct {
	Graph    *model.Graph // needed by presenters for derived attributes (status, topics)
	Sections []SectionResult
}

ViewResult is the structured output of a ViewQuery: one SectionResult per section in the source layout, in the order they appeared.

type WIPListQuery ¶

type WIPListQuery struct {
	GraphDir string
}

WIPListQuery captures intent to list active WIP markers.

type WIPListResult ¶

type WIPListResult struct {
	Markers []*model.WIPMarker
}

WIPListResult is the structured output of a WIPListQuery.