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's tasks have comments at all.
30 ///
31 /// Read exactly as [`documents`](Self::documents) is: it says what the source *holds*,
32 /// not which predicate it applies, so the second capability rule does not reach it. A
33 /// source declaring `Unsupported` is never sent a comment call — the engine reads this
34 /// once at the handshake and refuses such a call before anything is read, naming the
35 /// source and its plugin. Adding, editing and removing a comment is a write, so a source
36 /// declaring `Native` is written through only when
37 /// [`TaskSource::writes`](crate::TaskSource::writes) says it can be written at all.
38 ///
39 /// Defaulted to [`Support::Unsupported`] when a wire value omits it, so a plugin that
40 /// predates comments says nothing here and is read as the comment-free source it is.
41 // llmlint: ignore[names_match_behavior, invalid_states_unrepresentable] the reason recorded at `documents` above, at a new field: the contract says whether a source holds a kind of thing in the shape `projects` and `documents` already use, and a second enum here would say the same thing three ways for three sibling fields. Whether comments can be *written* is `TaskSource::writes`, the one write declaration every write of this contract already reads, so a read-only pairing is a source declaring `Native` here and `Unsupported` there rather than a third variant.
42 #[serde(default = "no_comments")]
43 pub comments: Support,
44 /// Whether the source can select tasks belonging to no project.
45 pub orphan_tasks: Support,
46 /// Whether the source filters by label itself.
47 pub filter_by_label: Support,
48 /// Whether the source filters by status itself.
49 pub filter_by_status: Support,
50 /// Whether the source searches titles itself.
51 pub search_title: Support,
52 /// Whether the source searches bodies itself.
53 pub search_content: Support,
54 /// How far the source can walk task dependencies.
55 pub task_dependencies: DependencySupport,
56 /// How far the source can walk project dependencies.
57 pub project_dependencies: DependencySupport,
58 /// The largest page the source will serve. At least 1 — a source that serves no rows
59 /// cannot be paged, and every implementation rejects zero where its config is read.
60 // 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.
61 // 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".
62 pub max_page_size: u32,
63}
64
65/// What [`Capabilities::documents`] means when a wire value does not carry it.
66///
67/// A named function rather than a `Default` on [`Support`], which has no sensible default
68/// of its own: an absent *predicate* declaration is a plugin that did not answer, while an
69/// absent document declaration is a plugin written before there were any.
70fn no_documents() -> Support {
71 Support::Unsupported
72}
73
74/// What [`Capabilities::comments`] means when a wire value does not carry it: a plugin
75/// written before there were comments, on the terms [`no_documents`] gives.
76fn no_comments() -> Support {
77 Support::Unsupported
78}
79
80/// Whether a source applies one predicate itself.
81///
82/// Keeps an `Unsupported` variant because in-memory compensation for a filter or
83/// a search is sound: the engine over-fetches and narrows. Do not conflate this
84/// with [`DependencySupport`], which has no such variant.
85#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize, JsonSchema)]
86#[serde(rename_all = "kebab-case")]
87pub enum Support {
88 /// The source applies this predicate itself.
89 Native,
90 /// The source ignores this predicate; the engine narrows the wider result.
91 Unsupported,
92}
93
94impl Support {
95 /// Whether the source applies the predicate itself.
96 #[must_use]
97 pub fn is_native(self) -> bool {
98 matches!(self, Self::Native)
99 }
100}
101
102/// How far a source can walk its own dependency edges.
103///
104/// There is deliberately **no** unsupported variant: dependency traversal is a
105/// guaranteed capability of this product, not one a source may opt out of. A
106/// source that cannot report an item's forward edges cannot implement
107/// [`TaskSource`](crate::TaskSource). The weakest declaration is
108/// [`ForwardOnly`](Self::ForwardOnly), which the engine answers in reverse by a
109/// bounded scan and reports as emulated.
110#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize, JsonSchema)]
111#[serde(rename_all = "kebab-case")]
112pub enum DependencySupport {
113 /// The source answers both directions itself.
114 BothDirections,
115 /// The source answers forward edges; the engine emulates the reverse.
116 ForwardOnly,
117}
118
119impl DependencySupport {
120 /// Whether the source answers the reverse direction itself.
121 #[must_use]
122 pub fn answers_reverse(self) -> bool {
123 matches!(self, Self::BothDirections)
124 }
125}