onetaskgraph_plugin_api/

work.rs

//! The work items every source is normalised into.

use chrono::{DateTime, Utc};
use schemars::{JsonSchema, Schema, SchemaGenerator, json_schema};
use serde::{Deserialize, Serialize};
use serde_json::Value;
use std::collections::BTreeMap;

use crate::{NativeId, SourceName};

/// One unit of work as a source reports it.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
pub struct Task {
    /// The source's own opaque identifier.
    pub id: NativeId,
    /// The short handle the backend shows people, beside [`id`](Self::id) and never
    /// instead of it — a Linear issue's `ENG-123`, a GitHub issue's `1043`.
    ///
    /// **It is human-facing and it may change.** A Linear issue moved between teams gets a
    /// new identifier and a GitHub issue transferred between repositories gets a new
    /// number, so nothing stores this in place of [`id`](Self::id) and nothing matches on
    /// it: `id` is what everything stores and matches on, and this is what a person says
    /// out loud.
    ///
    /// Absent by default, so a source that predates this field — and every source with no
    /// separate handle of its own — reads as `None`, which means *this backend has no
    /// short handle for this task* rather than *the handle is the id*. A source never
    /// copies [`id`](Self::id) here.
    ///
    /// **Read-only.** A source derives it on a read and never stores one it is handed: a
    /// task arriving on an [`ItemWrite`](crate::ItemWrite) may still hold its source's key,
    /// and a destination ignores it.
    // llmlint: ignore[invalid_states_unrepresentable] The answer `Task::url` and `Project::url` below already record: this crate's field types are the contract itself, and the contract approving this field states its shape as `Option<String>`. A backend's handle is also the one value this product never parses, matches on or resolves by — `id` does all three — so the confusion a newtype prevents is confusion no code here can act on.
    #[serde(default)]
    pub key: Option<String>,
    /// The one-line summary a user recognises the task by.
    pub title: String,
    /// The long-form body, when the source has one.
    pub content: Option<String>,
    /// The source's status, normalised and preserved.
    pub status: Status,
    /// Inline rather than by id: a source returning a task already knows them.
    pub labels: Vec<Label>,
    /// `None` is a first-class case — an orphan task — not an edge case.
    pub project: Option<NativeId>,
    /// Where a human can open this task.
    // llmlint: ignore[invalid_states_unrepresentable] SECOND PERMITTED REASON — this restates at a new site the justification already recorded at `Capabilities.max_page_size` (capability.rs) and `PageRequest.limit` (query.rs), and in AGENTS.md's "The plugin contract": this crate's field types ARE the approved contract, six undispatched nodes compile against `Option<String>` here, and only the contract's owner may narrow one. No code change is available that clears this without editing that frozen surface.
    // llmlint: ignore[boundary_inputs_validated] parsing this into a URL type would narrow the same frozen surface, and would add a URL dependency to the crate AGENTS.md says to keep still ("Keep the api crate still" — every change here re-tests every plugin). A plugin that returns a string this interface cannot represent is what `SourceError::Malformed` is for. Contract owner's call; recorded in AGENTS.md, "The plugin contract".
    pub url: Option<String>,
    /// Where this task is, when the source says (see [`Location`]).
    ///
    /// Absent by default, so a source that predates this field — and every source that
    /// simply does not say — reads as `None`, which means *the source did not say where
    /// this is* rather than *this is nowhere*. It neither replaces nor derives from
    /// [`url`](Self::url), which goes on meaning exactly what it always did.
    #[serde(default)]
    pub location: Option<Location>,
    /// When the source says the task was created.
    pub created_at: Option<DateTime<Utc>>,
    /// When the source says the task last changed.
    pub updated_at: Option<DateTime<Utc>>,
    /// Caller-defined attributes, preserving their JSON types.
    ///
    /// Keys are free-form, with two reserved prefixes: `onetaskgraph.` belongs to this
    /// product — [`Repository::METADATA_KEY`] and [`DependencyEdge::RECORDED_KEY`] are
    /// the two every source honours, and [`ItemKind::METADATA_KEY`] is one plugin's —
    /// and `onepipeline.` belongs to that consumer. Every other key is the caller's, and
    /// a source returns it exactly as it holds it.
    #[serde(default)]
    pub metadata: BTreeMap<String, Value>,
    /// Normalized repository origins this task concerns, in source order and without
    /// repeats.
    #[serde(default, deserialize_with = "unique_repositories")]
    pub repositories: Vec<Repository>,
    /// The tasks this one delivers: finishing this task finishes them.
    ///
    /// Each entry is a [`TaskRef`] — `<source>:<native>` names a task of any source, and a
    /// bare native id names a task of the source holding this one — with no repeats and
    /// never this task itself. Empty by default, and left out of the wire when empty, so a
    /// reader written before the field existed reads exactly what it read before.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    #[schemars(!skip_serializing_if)]
    pub delivers: Vec<TaskRef>,
    /// Every task that delivers this one, by qualified id: the reverse of [`Self::delivers`].
    ///
    /// **Owned by the store, not by a source record and not by a copy.** The engine keeps it
    /// in step whenever it writes a task's `delivers`, through
    /// [`TaskSource::set_delivered_by`](crate::TaskSource::set_delivered_by); a source holds
    /// and reports it, and a copy keeps the destination's own rather than taking the
    /// source's. Empty by default and left out of the wire when empty, as `delivers` is.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    #[schemars(!skip_serializing_if)]
    pub delivered_by: Vec<TaskRef>,
}

/// A grouping of tasks, shaped like a [`Task`] without a parent of its own.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
pub struct Project {
    /// The source's own opaque identifier.
    pub id: NativeId,
    /// The one-line summary a user recognises the project by.
    pub title: String,
    /// The long-form body, when the source has one.
    pub content: Option<String>,
    /// The source's status, normalised and preserved.
    pub status: Status,
    /// Inline rather than by id, for the same reason as on [`Task`].
    pub labels: Vec<Label>,
    /// Where a human can open this project.
    // llmlint: ignore[invalid_states_unrepresentable] SECOND PERMITTED REASON — this restates at a new site the justification already recorded at `Capabilities.max_page_size` (capability.rs) and `PageRequest.limit` (query.rs), and in AGENTS.md's "The plugin contract": this crate's field types ARE the approved contract, six undispatched nodes compile against `Option<String>` here, and only the contract's owner may narrow one. No code change is available that clears this without editing that frozen surface.
    // llmlint: ignore[boundary_inputs_validated] parsing this into a URL type would narrow the same frozen surface, and would add a URL dependency to the crate AGENTS.md says to keep still ("Keep the api crate still" — every change here re-tests every plugin). A plugin that returns a string this interface cannot represent is what `SourceError::Malformed` is for. Contract owner's call; recorded in AGENTS.md, "The plugin contract".
    pub url: Option<String>,
    /// Where this project is, on exactly the terms of [`Task::location`].
    #[serde(default)]
    pub location: Option<Location>,
    /// When the source says the project was created.
    pub created_at: Option<DateTime<Utc>>,
    /// When the source says the project last changed.
    pub updated_at: Option<DateTime<Utc>>,
    /// Caller-defined attributes, preserving their JSON types, on the same terms as
    /// [`Task::metadata`].
    #[serde(default)]
    pub metadata: BTreeMap<String, Value>,
    /// Normalized repository origins this project concerns, in source order and without
    /// repeats.
    #[serde(default, deserialize_with = "unique_repositories")]
    pub repositories: Vec<Repository>,
}

/// One piece of information that lives in a project and is not work.
///
/// A document carries **no status** and **no dependencies**, and both omissions are the
/// contract rather than an oversight: a document is not work, so it has no place in a
/// status filter and no place in a dependency graph. [`ItemKind`] therefore gains no
/// document variant — that enum names what a dependency endpoint points at, and nothing
/// may point at a document.
///
/// A source says whether it has documents at all through
/// [`Capabilities::documents`](crate::Capabilities::documents), and one that says it has
/// none is never asked for one.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
pub struct Document {
    /// The source's own opaque identifier.
    pub id: NativeId,
    /// The one-line summary a person recognises it by.
    pub title: String,
    /// The long-form body, when the source has one.
    pub content: Option<String>,
    /// The project it lives in; `None` is an orphan document, exactly as it is on a
    /// [`Task`].
    pub project: Option<NativeId>,
    /// Inline, on the same terms as a [`Task`]'s.
    pub labels: Vec<Label>,
    /// Where a person can open it, on the same terms as a [`Task`]'s.
    // llmlint: ignore[invalid_states_unrepresentable] SECOND PERMITTED REASON — this restates at a new site the justification already recorded at `Task::url` and `Project::url` in this module, at `Capabilities.max_page_size` (capability.rs) and `PageRequest.limit` (query.rs), and in AGENTS.md's "The plugin contract": this crate's field types ARE the approved contract, this field is `Option<String>` because a task's and a project's are, and only the contract's owner may narrow one. Narrowing it here alone would leave the three entities describing the same thing in two different types.
    // llmlint: ignore[boundary_inputs_validated] parsing this into a URL type would narrow the same frozen surface, and would add a URL dependency to the crate AGENTS.md says to keep still ("Keep the api crate still" — every change here re-tests every plugin). A plugin that returns a string this interface cannot represent is what `SourceError::Malformed` is for. Contract owner's call; recorded in AGENTS.md, "The plugin contract".
    pub url: Option<String>,
    /// Where it is, when the source says (see [`Location`]).
    #[serde(default)]
    pub location: Option<Location>,
    /// When the source says it was created.
    pub created_at: Option<DateTime<Utc>>,
    /// When the source says it last changed.
    pub updated_at: Option<DateTime<Utc>>,
    /// Caller-defined attributes, preserving their JSON types, with the same reserved
    /// prefixes [`Task::metadata`] carries.
    #[serde(default)]
    pub metadata: BTreeMap<String, Value>,
    /// Normalized repository origins this document concerns, in source order and without
    /// repeats, as a [`Task`]'s.
    #[serde(default, deserialize_with = "unique_repositories")]
    pub repositories: Vec<Repository>,
}

/// Where an entity is, in the one form a consumer can act on without knowing the backend.
///
/// Externally tagged with exactly two variants, so the JSON is `{"url": "https://…"}` or
/// `{"path": "/home/…"}` and a consumer tells them apart by which key is present. A reader
/// handed one of these knows what to *do* with it — open a link, or print a path and read
/// the file out — which is what a bare string could not have said.
///
/// It carries no third case on purpose. `None` on the field is the third case, and it
/// means the source did not say where the entity is, which is not the same as saying it is
/// nowhere.
///
/// This does **not** redefine, replace or derive from the `url` field of [`Task`],
/// [`Project`] or [`Document`]: a source that reports a web URL there goes on reporting
/// it, and every existing consumer sees exactly what it saw.
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "kebab-case")]
pub enum Location {
    /// The entity lives at an external website, and this is a link a reader can open.
    // llmlint: ignore[invalid_states_unrepresentable] SECOND PERMITTED REASON — this restates at a new site the justification already recorded at `Task::url` and `Project::url` in this module, at `Capabilities.max_page_size` (capability.rs) and `PageRequest.limit` (query.rs): this crate's field types ARE the approved contract, and this variant is a `String` because the `url` field it sits beside is one. Narrowing it here alone would leave two members describing a web address in two different types, which is worse than the state it would remove.
    // llmlint: ignore[boundary_inputs_validated] parsing this into a URL type would add a URL dependency to the crate AGENTS.md says to keep still ("Keep the api crate still" — every change here rebuilds and re-tests every plugin), and would narrow a frozen surface only the contract's owner may narrow. A plugin returning a string this interface cannot represent is what `SourceError::Malformed` is for, exactly as it is for `Task::url`.
    Url(String),
    /// The entity is a file on the machine the source runs on, and this is that file's
    /// absolute path, so a reader can print the path or read the contents out.
    // llmlint: ignore[invalid_states_unrepresentable] SECOND PERMITTED REASON — the reason the variant above carries, plus one of this variant's own: a typed path here would be `std::path::PathBuf`, whose parsing is the *reading* platform's while this string is the *source's*. A plugin on Linux reporting an absolute path to an engine on Windows must have that path survive byte for byte, so the type that would make a relative path unrepresentable is the type that would corrupt a correct one.
    // llmlint: ignore[boundary_inputs_validated] validating absoluteness here would answer the question with the wrong machine's rules, for the reason above — this side cannot know what "absolute" means on the host the plugin runs on. The absoluteness this documents is an obligation on the source, and a source that breaks it is `SourceError::Malformed` to the reader that acts on the path.
    Path(String),
}

/// A repository identified by its normalized origin, without a URL scheme or `.git` suffix.
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize, JsonSchema)]
#[serde(try_from = "String", into = "String")]
pub struct Repository(String);

impl Repository {
    /// The reserved metadata key a source reads these origins from when its backend has
    /// no notion of its own.
    ///
    /// The key is spelled once, here, because every plugin has to agree on it: a source
    /// that invented its own spelling would hold work nothing else could read.
    pub const METADATA_KEY: &'static str = "onetaskgraph.repositories";

    /// The normalized `host/owner/name` origin.
    #[must_use]
    pub fn as_str(&self) -> &str {
        &self.0
    }

    /// The origins a source records under [`Self::METADATA_KEY`], or none.
    ///
    /// # Errors
    ///
    /// Returns a message when the key holds something other than a duplicate-free list
    /// of normalized origins.
    pub fn from_metadata(metadata: &BTreeMap<String, Value>) -> Result<Vec<Self>, String> {
        let Some(value) = metadata.get(Self::METADATA_KEY) else {
            return Ok(Vec::new());
        };
        let origins: Vec<Self> = serde_json::from_value(value.clone()).map_err(|error| {
            format!(
                "{} is not a list of repository origins: {error}",
                Self::METADATA_KEY
            )
        })?;
        Self::unique(origins)
    }

    /// The same origins, in the order given, once it is established none repeats.
    ///
    /// # Errors
    ///
    /// Returns a message naming the first origin that appears twice.
    pub fn unique(origins: Vec<Self>) -> Result<Vec<Self>, String> {
        let mut seen = std::collections::BTreeSet::new();
        for origin in &origins {
            if !seen.insert(origin.as_str()) {
                return Err(format!(
                    "{:?} is listed twice; a repository list names each origin once",
                    origin.as_str()
                ));
            }
        }
        Ok(origins)
    }
}

fn unique_repositories<'de, D>(deserializer: D) -> Result<Vec<Repository>, D::Error>
where
    D: serde::Deserializer<'de>,
{
    Repository::unique(Vec::<Repository>::deserialize(deserializer)?)
        .map_err(serde::de::Error::custom)
}

impl TryFrom<String> for Repository {
    type Error = String;

    fn try_from(origin: String) -> Result<Self, Self::Error> {
        let valid = !origin.is_empty()
            && !origin.contains("://")
            && !origin.ends_with(".git")
            && !origin.chars().any(char::is_whitespace)
            && origin.split('/').count() >= 3
            && origin
                .split('/')
                .all(|part| !part.is_empty() && part != "." && part != "..");
        valid.then_some(Self(origin.clone())).ok_or_else(|| format!(
            "{origin:?} is not a normalized repository origin; use host/owner/name without a scheme or .git suffix"
        ))
    }
}

impl From<Repository> for String {
    fn from(repository: Repository) -> Self {
        repository.0
    }
}

/// One task named by another task's [`Task::delivers`] or [`Task::delivered_by`].
///
/// A string with one of two spellings, decided the way a [`DependencyEndpoint`] decides it:
/// one holding a colon is `<source>:<native>` and names a task of any source, and one
/// without is a bare native id naming a task of the source that holds the list. So a
/// native id holding a colon cannot be named bare, exactly as it cannot in
/// `onetaskgraph.depends_on`.
#[derive(
    Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize, JsonSchema,
)]
#[serde(try_from = "String", into = "String")]
pub struct TaskRef(String);

impl TaskRef {
    /// The reserved metadata key a source records [`Task::delivers`] under when its backend
    /// has no notion of its own.
    ///
    /// Spelled once, here, for the reason [`Repository::METADATA_KEY`] is.
    pub const DELIVERS_KEY: &'static str = "onetaskgraph.delivers";

    /// The reserved metadata key a source records [`Task::delivered_by`] under when its
    /// backend has no notion of its own.
    pub const DELIVERED_BY_KEY: &'static str = "onetaskgraph.delivered_by";

    /// One entry, once it is established it is a task id.
    ///
    /// # Errors
    ///
    /// Returns a message saying why when the id is empty, or when it is qualified with a
    /// source name that breaks the pattern or with no native id after the colon.
    pub fn new(id: impl Into<String>) -> Result<Self, String> {
        let id = id.into();
        if id.is_empty() {
            return Err("an empty string names no task".to_owned());
        }
        if let Some((source, native)) = id.split_once(':') {
            SourceName::new(source).map_err(|error| error.to_string())?;
            if native.is_empty() {
                return Err(format!("{id:?} names a source and no task in it"));
            }
        }
        Ok(Self(id))
    }

    /// The qualified entry naming `native` in `source`.
    #[must_use]
    pub fn qualified(source: &SourceName, native: &NativeId) -> Self {
        Self(format!("{source}:{native}"))
    }

    /// The entry as it is spelled.
    #[must_use]
    pub fn as_str(&self) -> &str {
        &self.0
    }

    /// Whether the entry names its source in writing.
    #[must_use]
    pub fn is_qualified(&self) -> bool {
        self.0.contains(':')
    }

    /// The source and the native id this entry names, reading a bare entry as naming a task
    /// of `near_source`.
    #[must_use]
    pub fn parts<'a>(&'a self, near_source: &'a str) -> (&'a str, &'a str) {
        self.0
            .split_once(':')
            .unwrap_or((near_source, self.0.as_str()))
    }

    /// This entry qualified, reading a bare one as naming a task of `near_source`.
    #[must_use]
    pub fn in_source(&self, near_source: &SourceName) -> Self {
        if self.is_qualified() {
            return self.clone();
        }
        Self(format!("{near_source}:{}", self.0))
    }

    /// The entries of one task's list, once it is established that none names the task
    /// itself and none repeats.
    ///
    /// `field` is what the list is called where it is stored, for the message. `near` is the
    /// task holding the list and `near_source` the configured name of the source holding it,
    /// which is what tells `T-1` and `work:T-1` apart as the same task. A source that does
    /// not know its own name passes `None`, and then only a bare entry can be recognised as
    /// naming this task or one of the other entries.
    ///
    /// # Errors
    ///
    /// Returns a message naming the task and the entry.
    pub fn listed(
        field: &str,
        near: &NativeId,
        near_source: Option<&SourceName>,
        entries: Vec<Self>,
    ) -> Result<Vec<Self>, String> {
        let normal = |entry: &Self| match near_source {
            Some(source) => entry.in_source(source).0,
            None => entry.0.clone(),
        };
        let this = match near_source {
            Some(source) => Self::qualified(source, near).0,
            None => near.0.clone(),
        };
        let mut seen: Vec<(String, &Self)> = Vec::with_capacity(entries.len());
        for entry in &entries {
            let named = normal(entry);
            if named == this {
                return Err(format!(
                    "{field} on task {near} names {entry}, which is that task itself; a task \
                     cannot be listed in its own {field}"
                ));
            }
            if let Some((_, first)) = seen.iter().find(|(held, _)| *held == named) {
                return Err(format!(
                    "{field} on task {near} names {entry} more than once (as {first} and \
                     {entry}); name each task once"
                ));
            }
            seen.push((named, entry));
        }
        Ok(entries)
    }

    /// The entries one task's list holds, read out of the JSON a source stores it as.
    ///
    /// `value` is `None` when the source holds no list at all, which is the empty one.
    ///
    /// # Errors
    ///
    /// Returns a message naming the task and the entry when the value is not a list, when an
    /// entry is not a task id, or when [`Self::listed`] refuses the list.
    pub fn from_value(
        field: &str,
        near: &NativeId,
        near_source: Option<&SourceName>,
        value: Option<&Value>,
    ) -> Result<Vec<Self>, String> {
        let Some(value) = value else {
            return Ok(Vec::new());
        };
        let Some(held) = value.as_array() else {
            return Err(format!(
                "{field} on task {near} is {value}, which is not a list of task ids"
            ));
        };
        let entries = held
            .iter()
            .map(|entry| {
                entry
                    .as_str()
                    .ok_or_else(|| "it is not a string".to_owned())
                    .and_then(Self::new)
                    .map_err(|why| {
                        format!(
                            "{field} on task {near} holds {entry}, which is not a task id: {why}"
                        )
                    })
            })
            .collect::<Result<Vec<_>, _>>()?;
        Self::listed(field, near, near_source, entries)
    }
}

impl TryFrom<String> for TaskRef {
    type Error = String;

    fn try_from(id: String) -> Result<Self, Self::Error> {
        Self::new(id)
    }
}

impl From<TaskRef> for String {
    fn from(entry: TaskRef) -> Self {
        entry.0
    }
}

impl std::fmt::Display for TaskRef {
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        self.0.fmt(formatter)
    }
}

/// A tag a source attaches to work.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
pub struct Label {
    /// The source's own opaque identifier.
    pub id: NativeId,
    /// What a user filtering across sources actually types.
    pub name: String,
    /// The source's own colour for the label, when it has one.
    pub color: Option<String>,
}

/// A source's status, kept in both normalised and original form.
///
/// `category` is what every filter compares against; `name` is the source's own
/// wording, preserved so display never flattens "In Review" into "In Progress".
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
pub struct Status {
    /// The normalised value filters compare against.
    pub category: StatusCategory,
    /// The source's own label for this status.
    pub name: String,
}

/// The normalised status vocabulary shared across every source.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "kebab-case")]
pub enum StatusCategory {
    /// Written down but not yet committed to as work.
    Draft,
    /// Known about, not yet accepted as ready to work.
    Backlog,
    /// Accepted and ready to be picked up, and nothing has claimed it.
    Todo,
    /// Claimed by work that will do it, and not yet started.
    Queued,
    /// Being worked on.
    InProgress,
    /// Finished.
    Done,
    /// Abandoned.
    Cancelled,
    /// The source reported a status this vocabulary cannot place.
    Unknown,
}

/// A dependency between two work items.
///
/// An endpoint may name another source. Keeping that far id on the near item is work data
/// owned by its plugin, not an engine-side index or mirror; the engine reports it without
/// resolving or fetching the far item.
///
/// A source uses its backend's own relationship wherever that relationship can name the
/// far end, so the backend knows the graph and its own interface draws it. Where it
/// cannot — a far end in another source, which no backend relates — the source reads
/// [`Self::recorded`] from the near item instead. Only the forward direction is ever
/// recorded; the reverse of a recorded edge is derived, exactly as a
/// [`ForwardOnly`](crate::DependencySupport::ForwardOnly) source's reverse is.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
pub struct DependencyEdge {
    /// The item the edge starts at, and the one that **depends on** the other.
    ///
    /// This is the orientation every source reports in, whichever way its own backend
    /// spells the relationship: a GitHub `blockedBy` connection read for `ENG-1` yields
    /// `from: ENG-1`, because `ENG-1` is what depends.
    pub from: DependencyEndpoint,
    /// The item the edge points at, and the one that must finish first.
    pub to: DependencyEndpoint,
    /// What the edge means.
    pub kind: DependencyKind,
}

impl DependencyEdge {
    /// The reserved metadata key a near item records a far end under.
    ///
    /// Spelled once, here, for the reason [`Repository::METADATA_KEY`] is: a plugin that
    /// invented its own spelling would record a plan nothing else could read.
    pub const RECORDED_KEY: &'static str = "onetaskgraph.depends_on";

    /// The forward edges `near` records under [`Self::RECORDED_KEY`], or none.
    ///
    /// The key holds a list of endpoints — a bare string is a native id naming a task,
    /// and `{"id": "<source>:<native>", "kind": "project"}` names any item of any source.
    /// Each becomes one `blocks` edge from `near` to that endpoint.
    ///
    /// `natively_names` is the kind of item the near item's **own backend** can relate it
    /// to — `Some(ItemKind::Task)` for a GitHub issue, whose `blockedBy` connection holds
    /// issues; `None` for a GitHub draft, which has no such connection at all. An endpoint
    /// of that kind naming an item of `near_source` is refused, because it names an item
    /// the backend itself could hold, and the rule this key exists to serve is the
    /// backend's own relationship first. Naming one's own source is what an unqualified id
    /// does implicitly and what `<near_source>:<native>` does in writing, so both are
    /// refused: which of the two spellings a plan happened to use says nothing about where
    /// the edge belongs.
    ///
    /// An endpoint qualified to a *different* source is never refused. That is the whole
    /// case this key is for: no backend relates an id in a system it knows nothing about.
    ///
    /// # Errors
    ///
    /// Returns a message when the key holds anything other than a list of endpoints, or
    /// holds one the near item's own backend was supposed to name.
    pub fn recorded(
        metadata: &BTreeMap<String, Value>,
        near: &NativeId,
        near_kind: ItemKind,
        near_source: &SourceName,
        natively_names: Option<ItemKind>,
    ) -> Result<Vec<Self>, String> {
        let Some(value) = metadata.get(Self::RECORDED_KEY) else {
            return Ok(Vec::new());
        };
        let far: Vec<DependencyEndpoint> =
            serde_json::from_value(value.clone()).map_err(|error| {
                format!(
                    "{} is not a list of dependency endpoints: {error}",
                    Self::RECORDED_KEY
                )
            })?;
        far.into_iter()
            .map(|to| {
                let names_this_source = to
                    .source()
                    .is_none_or(|source| source == near_source.as_str());
                if names_this_source && natively_names == Some(to.kind) {
                    return Err(format!(
                        "{key} on {near} records {to}, which this source can relate \
                         natively; record it as this backend's own dependency and keep \
                         {key} for a far end no relationship here can name",
                        key = Self::RECORDED_KEY
                    ));
                }
                Ok(Self {
                    from: DependencyEndpoint::from_native(near.clone(), near_kind),
                    to,
                    kind: DependencyKind::Blocks,
                })
            })
            .collect()
    }
}

/// One endpoint of a dependency edge.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct DependencyEndpoint {
    /// A qualified `<source>:<native>` id, or a legacy native id which the engine
    /// qualifies to the source reporting the edge.
    id: EndpointIdentity,
    /// Whether the endpoint names a task or a project.
    pub kind: ItemKind,
}

#[derive(Debug, Clone, PartialEq, Eq, Hash)]
enum EndpointIdentity {
    Native(String),
    Qualified(String),
}

impl EndpointIdentity {
    fn as_str(&self) -> &str {
        match self {
            Self::Native(id) | Self::Qualified(id) => id,
        }
    }

    fn into_string(self) -> String {
        match self {
            Self::Native(id) | Self::Qualified(id) => id,
        }
    }
}

impl Serialize for DependencyEndpoint {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: serde::Serializer,
    {
        #[derive(Serialize)]
        struct Wire<'a> {
            id: &'a str,
            kind: ItemKind,
        }
        Wire {
            id: self.id(),
            kind: self.kind,
        }
        .serialize(serializer)
    }
}

impl JsonSchema for DependencyEndpoint {
    fn schema_name() -> std::borrow::Cow<'static, str> {
        "DependencyEndpoint".into()
    }

    fn json_schema(_generator: &mut SchemaGenerator) -> Schema {
        json_schema!({
            "description": "A dependency endpoint. A bare string is a native id of the source reporting it, and this decoding reads one as a task; a reader that knows the level it was written at — a source's own configuration, say — may read it at that level instead.",
            "oneOf": [
                {"type": "string", "minLength": 1},
                {
                    "type": "object",
                    "additionalProperties": false,
                    "required": ["id", "kind"],
                    "properties": {
                        "id": {"type": "string", "minLength": 1},
                        "kind": {"type": "string", "enum": ["task", "project"]}
                    }
                }
            ]
        })
    }
}

impl DependencyEndpoint {
    /// Builds an endpoint from a serialized id, validating a qualified id when present.
    ///
    /// # Errors
    ///
    /// Returns an error for an empty id or a malformed `<source>:<native>` id.
    pub fn new(id: String, kind: ItemKind) -> Result<Self, String> {
        let is_qualified = id.contains(':');
        let id = valid_endpoint_id(id)?;
        Ok(Self {
            id: if is_qualified {
                EndpointIdentity::Qualified(id)
            } else {
                EndpointIdentity::Native(id)
            },
            kind,
        })
    }

    /// Builds an endpoint from a source-native id, whose contents are deliberately opaque.
    #[must_use]
    pub fn from_native(id: NativeId, kind: ItemKind) -> Self {
        Self {
            id: EndpointIdentity::Native(id.0),
            kind,
        }
    }

    /// The serialized native or qualified id.
    #[must_use]
    pub fn id(&self) -> &str {
        self.id.as_str()
    }

    /// Consumes the endpoint and returns its serialized id.
    #[must_use]
    pub fn into_id(self) -> String {
        self.id.into_string()
    }

    /// Whether the id was explicitly supplied as a qualified endpoint.
    #[must_use]
    pub fn is_qualified(&self) -> bool {
        matches!(self.id, EndpointIdentity::Qualified(_))
    }

    /// The source segment of a qualified id, or `None` for a native one.
    ///
    /// A native id belongs to whichever source reports it, so `None` reads as "this
    /// source" rather than "no source".
    #[must_use]
    pub fn source(&self) -> Option<&str> {
        match &self.id {
            EndpointIdentity::Qualified(id) => id.split_once(':').map(|(source, _)| source),
            EndpointIdentity::Native(_) => None,
        }
    }
}

impl<'de> Deserialize<'de> for DependencyEndpoint {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: serde::Deserializer<'de>,
    {
        #[derive(Deserialize)]
        #[serde(untagged)]
        enum Wire {
            Legacy(String),
            Endpoint { id: String, kind: ItemKind },
        }
        match Wire::deserialize(deserializer)? {
            Wire::Legacy(id) => {
                if id.is_empty() {
                    return Err(serde::de::Error::custom(
                        "a dependency endpoint id cannot be empty",
                    ));
                }
                Ok(Self::from_native(NativeId(id), ItemKind::Task))
            }
            Wire::Endpoint { id, kind } => Self::new(id, kind).map_err(serde::de::Error::custom),
        }
    }
}

fn valid_endpoint_id(id: String) -> Result<String, String> {
    if id.is_empty() {
        return Err("a dependency endpoint id cannot be empty".into());
    }
    if let Some((source, native)) = id.split_once(':') {
        crate::SourceName::new(source).map_err(|error| error.to_string())?;
        if native.is_empty() {
            return Err("a qualified dependency endpoint must name a native id".into());
        }
    }
    Ok(id)
}

impl std::fmt::Display for DependencyEndpoint {
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        self.id().fmt(formatter)
    }
}

impl PartialEq<NativeId> for DependencyEndpoint {
    fn eq(&self, other: &NativeId) -> bool {
        self.id() == other.0
    }
}

/// The kind of work item named by a dependency endpoint.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "kebab-case")]
pub enum ItemKind {
    /// A task.
    Task,
    /// A project.
    Project,
}

impl ItemKind {
    /// The reserved metadata key an item is marked with when its backend cannot say
    /// which kind it is.
    ///
    /// Spelled once, here, for the reason [`Repository::METADATA_KEY`] is: a key under
    /// this product's prefix belongs to the product, and a plugin inventing its own
    /// spelling would collide with the next one to want it.
    ///
    /// Unlike the other two reserved keys, this one obliges **no** source. A backend that
    /// knows its own kinds — folders, native projects — never reads or writes it, and
    /// passes it through as ordinary caller metadata with its JSON type intact, exactly
    /// as it passes through every other key it does not own. `github-projects` is the one
    /// source that needs it, because a GitHub Projects board holds only issues and an
    /// empty project is indistinguishable from a task without it.
    pub const METADATA_KEY: &'static str = "onetaskgraph.item_kind";

    /// The value this kind is marked with under [`Self::METADATA_KEY`].
    #[must_use]
    pub const fn marker(self) -> &'static str {
        match self {
            Self::Task => "task",
            Self::Project => "project",
        }
    }

    /// The kind `metadata` marks, or `None` when it carries no marker at all.
    ///
    /// # Errors
    ///
    /// Returns a message when [`Self::METADATA_KEY`] holds anything other than the two
    /// markers [`Self::marker`] spells.
    pub fn from_metadata(metadata: &BTreeMap<String, Value>) -> Result<Option<Self>, String> {
        let Some(value) = metadata.get(Self::METADATA_KEY) else {
            return Ok(None);
        };
        match value.as_str() {
            Some(marker) if marker == Self::Task.marker() => Ok(Some(Self::Task)),
            Some(marker) if marker == Self::Project.marker() => Ok(Some(Self::Project)),
            _ => Err(format!(
                "{} is {value}; it accepts only {:?} or {:?}",
                Self::METADATA_KEY,
                Self::Project.marker(),
                Self::Task.marker()
            )),
        }
    }
}

/// What a [`DependencyEdge`] means.
///
/// Both variants are read in the one direction [`DependencyEdge::from`] fixes: `from`
/// depends on `to`. This enum said the opposite of that until the orientation was settled,
/// which is why it is spelled out twice rather than once.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "kebab-case")]
pub enum DependencyKind {
    /// `from` depends on `to`, and `to` must finish before `from` can.
    // llmlint: ignore[names_match_behavior] `"blocks"` is the approved serialized value, spelled in docs/plugin-protocol.md §4.8 and both generated SDKs; the variant names the kind of dependency, and `from`/`to` carry the direction. Renaming it is a wire change and the contract owner's call.
    Blocks,
    /// `from` and `to` are linked without an ordering.
    Related,
}

/// Which way a dependency query walks the graph.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "kebab-case")]
pub enum Direction {
    /// What this item depends on — the forward edges every source can report.
    DependsOn,
    /// What depends on this item — emulated by the engine for a
    /// [`ForwardOnly`](crate::DependencySupport::ForwardOnly) source.
    DependedOnBy,
}