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 Finding ¶

type Finding struct {
	Severity    Severity
	Category    string
	Observation string
}

Finding is a single observation from pre-flight validation.

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
}

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) are populated by the CLI lint action when an embedding provider is configured — the finder itself stays pure-graph. They surface the search index's health alongside graph health so a single `sdd lint` run reports both.

type ListQuery ¶

type ListQuery struct {
	Graph  *model.Graph
	Filter model.GraphFilter
	// Topic optionally narrows results to entries whose effective topic set
	// (inline `topics:` ∪ topics declared by annotations whose refs include
	// the entry) has any label with the given path as a component-wise,
	// case-insensitive prefix. Zero value means no topic filter.
	Topic model.TopicPath
}

ListQuery captures intent to filter graph entries.

type ListResult ¶

type ListResult struct {
	Graph   *model.Graph // needed to render derived attributes like status
	Entries []*model.Entry
}

ListResult is the structured output of a ListQuery.

type ParticipantGroup ¶ added in v0.3.0

type ParticipantGroup struct {
	Actor *model.Entry   // the active actor head (kind: actor signal)
	Roles []*model.Entry // derived-active roles whose cascade resolves to this actor's chain
}

ParticipantGroup couples an active actor head with its derived-active role decisions for the status Participants block per plan d-cpt-d34 AC 15. Grouping is materialized in the finder so the presenter stays a pure view layer.

type PreflightQuery ¶

type PreflightQuery struct {
	Entry   *model.Entry
	Graph   *model.Graph
	Model   string        // LLM model identifier (e.g. "claude-haiku-4-5-20251001")
	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 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
}

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

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 — same shape as ListQuery.
	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 caps the number of citations a single entry
	// may contribute. Zero means DefaultMaxCitationsPerEntry. Set to 1
	// for one-citation-per-entry rendering; higher to surface more of
	// an entry's matching surface (e.g. for explore-mode briefings
	// where the breadth of why-it-matched is informative).
	MaxCitationsPerEntry int
}

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
}

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
	Upstream   []model.ShowTreeItem
	Downstream []model.ShowTreeItem
}

ShowGroup is one primary's full tree: the primary entry, its upstream chain, and its downstream chain. Multiple groups are joined with separators.

type ShowQuery ¶

type ShowQuery struct {
	Graph      *model.Graph
	IDs        []string
	MaxDepth   int  // depth limit for upstream/downstream expansion; 0 = no expansion
	Downstream bool // include downstream entries (refd-by, closed-by, superseded-by)
}

ShowQuery captures intent to render a set of entries with their reference chains. Upstream is always included; downstream requires opt-in.

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 StatusQuery ¶

type StatusQuery struct {
	Graph          *model.Graph
	RecentDone     int // how many recent kind: done signals to include (default 10)
	RecentInsights int // how many recent kind: insight signals to include (default 10)
}

StatusQuery captures intent to summarise current graph state.

type StatusResult ¶

type StatusResult struct {
	Graph            *model.Graph // for top-line counts (entries, decisions, signals)
	LocalParticipant string       // canonical from config; empty means "not configured"
	Language         string       // configured graph language (locale code); empty means English default
	// Search renders as `Search: text` when only text mode is available,
	// `Search: vector,text` when an embedding provider is configured. The
	// finder fills this from the SDD config alone — actual index health
	// is reported by `sdd lint`, not the header.
	Search       string
	Aspirations  []*model.Entry
	Contracts    []*model.Entry
	Plans        []*model.Entry
	Activities   []*model.Entry
	Directives   []*model.Entry
	Open         []*model.Entry // kind: gap and kind: question signals (the actionable set)
	Insights     []*model.Entry // recent kind: insight signals
	Recent       []*model.Entry // recent kind: done signals
	Participants []ParticipantGroup
}

StatusResult is the structured snapshot of graph state for the status view. Each decision kind surfaces in its own section — Aspirations guide, Contracts bound, Plans carry multi-step scope with ACs, Activities capture THAT-shaped commitments that specific work happens, Directives are the WHAT-shaped choices. On the signal side, Open carries the closure-gated attention set (gap + question), Insights and Recent are truncated activity streams.

LocalParticipant surfaces the canonical participant name from .sdd/config.local.yaml so agents reading the status header see ground truth without inferring from entries (which may contain drift).

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

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.