onetaskgraph_plugin_api/
capability.rs

1//! What a source declares it can do natively, so the engine can compensate for
2//! the rest instead of reducing every source to the weakest one's floor.
3
4use schemars::JsonSchema;
5use serde::{Deserialize, Serialize};
6
7/// One source's declared abilities.
8#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
9pub struct Capabilities {
10    /// Whether the source has projects at all.
11    pub projects: Support,
12    /// Whether the source has documents at all.
13    ///
14    /// The same shape as [`projects`](Self::projects), and read the same way: it says what
15    /// the source *holds*, not which predicate it applies. It is therefore **not** one of
16    /// the predicates the second capability rule reaches — there is no wider result set to
17    /// return and nothing for the engine to narrow. A source declaring `Unsupported` is
18    /// never asked for a document at all; the engine reads this once at the handshake,
19    /// exactly as it reads [`TaskSource::writes`](crate::TaskSource::writes), and a
20    /// document read across several sources reports such a source as holding none rather
21    /// than as having failed.
22    ///
23    /// Defaulted to [`Support::Unsupported`] when a wire value omits it, so a plugin that
24    /// predates documents says nothing here and is read as the document-free source it is.
25    // llmlint: ignore[names_match_behavior] SECOND PERMITTED REASON — this restates at a new field the justification recorded across this crate (`Capabilities.max_page_size` below, `PageRequest.limit` in query.rs, `Task::url` in work.rs) and in AGENTS.md's "The plugin contract": the approved contract specifies this field as a `Support` *in the shape `projects` already uses*, and `projects` has carried exactly this meaning — "the source has projects at all" — since before this change, as AGENTS.md and every plugin's verdict table record. A second enum here would say the same thing two ways for two sibling fields and change the serialized form of a frozen handshake. Renaming or re-typing either is the contract owner's call, not this crate's.
26    // llmlint: ignore[invalid_states_unrepresentable] the unrepresentable state named — "has documents, but some document predicate needs compensation" — is not a state this contract has: a `DocumentQuery`'s predicates are the same `text`/`labels`/`project` the task and project queries carry, and `filter_by_label`, `search_title` and `search_content` already declare how the source applies each of them, over whichever entity it is asked for. Adding a per-entity predicate axis is a contract change with no caller yet, and it would have to reach `projects` in the same breath. Recorded in AGENTS.md, "The three capability rules".
27    #[serde(default = "no_documents")]
28    pub documents: Support,
29    /// Whether the source can select tasks belonging to no project.
30    pub orphan_tasks: Support,
31    /// Whether the source filters by label itself.
32    pub filter_by_label: Support,
33    /// Whether the source filters by status itself.
34    pub filter_by_status: Support,
35    /// Whether the source searches titles itself.
36    pub search_title: Support,
37    /// Whether the source searches bodies itself.
38    pub search_content: Support,
39    /// How far the source can walk task dependencies.
40    pub task_dependencies: DependencySupport,
41    /// How far the source can walk project dependencies.
42    pub project_dependencies: DependencySupport,
43    /// The largest page the source will serve. At least 1 — a source that serves no rows
44    /// cannot be paged, and every implementation rejects zero where its config is read.
45    // llmlint: ignore[invalid_states_unrepresentable] this field's wire shape is frozen by the plugin contract every source is written against; only the contract's owner may change it, and tightening it is post-build follow-up.
46    // llmlint: ignore[boundary_inputs_validated] the boundary that reads a user's configuration does reject zero — `CapabilityConfig::max_page_size` (onetaskgraph-in-memory/src/config.rs) is a `NonZeroU32` and names the setting when it refuses. What stays a plain `u32` is this frozen contract field, which only the contract's owner may narrow — AGENTS.md, "The plugin contract".
47    pub max_page_size: u32,
48}
49
50/// What [`Capabilities::documents`] means when a wire value does not carry it.
51///
52/// A named function rather than a `Default` on [`Support`], which has no sensible default
53/// of its own: an absent *predicate* declaration is a plugin that did not answer, while an
54/// absent document declaration is a plugin written before there were any.
55fn no_documents() -> Support {
56    Support::Unsupported
57}
58
59/// Whether a source applies one predicate itself.
60///
61/// Keeps an `Unsupported` variant because in-memory compensation for a filter or
62/// a search is sound: the engine over-fetches and narrows. Do not conflate this
63/// with [`DependencySupport`], which has no such variant.
64#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize, JsonSchema)]
65#[serde(rename_all = "kebab-case")]
66pub enum Support {
67    /// The source applies this predicate itself.
68    Native,
69    /// The source ignores this predicate; the engine narrows the wider result.
70    Unsupported,
71}
72
73impl Support {
74    /// Whether the source applies the predicate itself.
75    #[must_use]
76    pub fn is_native(self) -> bool {
77        matches!(self, Self::Native)
78    }
79}
80
81/// How far a source can walk its own dependency edges.
82///
83/// There is deliberately **no** unsupported variant: dependency traversal is a
84/// guaranteed capability of this product, not one a source may opt out of. A
85/// source that cannot report an item's forward edges cannot implement
86/// [`TaskSource`](crate::TaskSource). The weakest declaration is
87/// [`ForwardOnly`](Self::ForwardOnly), which the engine answers in reverse by a
88/// bounded scan and reports as emulated.
89#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize, JsonSchema)]
90#[serde(rename_all = "kebab-case")]
91pub enum DependencySupport {
92    /// The source answers both directions itself.
93    BothDirections,
94    /// The source answers forward edges; the engine emulates the reverse.
95    ForwardOnly,
96}
97
98impl DependencySupport {
99    /// Whether the source answers the reverse direction itself.
100    #[must_use]
101    pub fn answers_reverse(self) -> bool {
102        matches!(self, Self::BothDirections)
103    }
104}
onetaskgraph_plugin_api/capability.rs

onetaskgraph_plugin_api/
capability.rs
