--- id: plugins-task-dependency-edge-ends title: Dependency edge ends on the plugin data API status: draft system: plugins owners: - kandev created: 2026-09-17 last_updated: 2026-09-17 --- # Dependency edge ends on the plugin data API Requirements ## Overview The [task dependency projection](task-dependency-projection.md) adds each task's direct predecessors and dependents to the plugin and canvas task read model. Each entry in those lists names *another* task, and carries that task's title and state. Those entries are where the projection stops describing the task the caller asked for and starts describing one it did not, so they raise two questions the projection itself does not answer. **Who may read an end.** On a canvas surface an entry can describe a task the caller is refused outright: a task-scoped canvas may read exactly one task, yet an unredacted end would hand it the titles of every task blocking that one. `REQ-PLUGINS-TASK-DEPS-003` bounds that disclosure. **What an end says when the response does not contain it.** A graph assembled from one page names ends that are archived, on another page, or gone from storage entirely. `REQ-PLUGINS-TASK-DEPS-006` fixes what each of those reports, so a consumer never renders a stale or invented node. This document is separated from the projection requirements because the two are reviewed against different risks: the projection decides what the graph says, and this decides what each end of it is allowed to say. The projection's criteria defer here wherever an end's `title`, `state`, or existence is at stake. A third sibling, [response bounds](task-dependency-response-bounds.md), owns `REQ-PLUGINS-TASK-DEPS-004`; the query bound that `AC-PLUGINS-TASK-DEPS-003.3` keeps the admission test inside lives there. Identities continue the `TASK-DEPS` token, so `REQ-PLUGINS-TASK-DEPS-003` and `REQ-PLUGINS-TASK-DEPS-006` keep the identities they were reviewed under. ## Terminology - **Dependency edge:** A directed peer-to-peer relation "this task depends on that task", distinct from the parent/child subtask hierarchy. Its two ends are the **predecessor** and the **dependent**, listed in `depends_on` and in `blocks` respectively; **edge end** means either. - **Canvas scope:** The scope kind and trusted resource identity bound to a canvas instance (instance, workspace, task, repository, or session), which already decides which tasks that canvas may read directly. - **Redaction:** Emptying an edge end's `title` and `state` while keeping the entry, its `id`, and (for a predecessor) its `status`. - **Plugin task read:** As defined in [task dependency projection](task-dependency-projection.md) — any surface returning the plugin task read model, on either the gRPC or the canvas surface. ## Requirements ### REQ-PLUGINS-TASK-DEPS-003: Scope-bounded edge ends **Intent:** An edge end must not become a way to read a task the caller is refused directly. A task-scoped canvas sees that its task is blocked; it must not learn the titles of the tasks blocking it. #### Acceptance criteria - **AC-PLUGINS-TASK-DEPS-003.1:** When a plugin task read on a canvas surface returns an edge end the canvas scope would not admit as a directly readable task, that entry shall carry only the end's `id` and, for a `depends_on` entry, its `status`. This shall hold on the list route, the single-task route, and the task object returned by the update route alike. - **AC-PLUGINS-TASK-DEPS-003.2:** A redacted entry shall report `title` and `state` as empty rather than omitting the entry. - **AC-PLUGINS-TASK-DEPS-003.3:** The admission test for an edge end shall be the same scope predicate that decides direct readability, evaluated only over data the response has already loaded. It shall issue no additional read per edge end, so it cannot conflict with `AC-PLUGINS-TASK-DEPS-004.1`. An end whose predicate inputs are unavailable shall be treated as not admitted. - **AC-PLUGINS-TASK-DEPS-003.4:** The cross-workspace write validator shall not be relied on as a blanket exemption from the workspace test in `AC-PLUGINS-TASK-DEPS-003.8`, because it does not reject a pair in which either end carries no workspace. - **AC-PLUGINS-TASK-DEPS-003.5:** A gRPC plugin read shall redact no edge end, on the grounds of disclosure parity rather than of a workspace filter: that surface has no canvas scope, and the caller may already read any such end as a task through the single-task read, which applies no workspace narrowing. The list read's narrowing shall not be cited, because it does not apply on every gRPC task read. - **AC-PLUGINS-TASK-DEPS-003.6:** Redaction shall not change `blocked`, `blocked_reason`, `start_when_unblocked`, the number of entries in either list, or their order. - **AC-PLUGINS-TASK-DEPS-003.7:** No field shall be added to report that an entry was redacted, and consumers shall be documented as rendering an empty `title` as an unlabelled node. The contract shall not claim a redacted entry is indistinguishable from one whose task genuinely has an empty title: it is not, because such a task still reports a non-empty `state`. - **AC-PLUGINS-TASK-DEPS-003.8:** The admission test shall resolve by scope kind as follows and admit no other end: instance scope admits every end; workspace scope admits an end whose workspace is known equal to the bound workspace; task scope admits no end, because an end is never the bound task itself; repository and session scope admit an end only when it is also returned in the response as a directly readable task. ### REQ-PLUGINS-TASK-DEPS-006: Archived and removed edge ends **Intent:** A graph assembled from one page has ends the page does not contain. The consumer must render them without being told a stale story about them. #### Acceptance criteria - **AC-PLUGINS-TASK-DEPS-006.1:** An archived predecessor shall appear in `depends_on` with `status: pending`, and shall never report `resolved`. - **AC-PLUGINS-TASK-DEPS-006.2:** An edge end shall appear in its list whether or not the same response contains that end as a task, so a default `include_archived=false` list still names its archived ends. - **AC-PLUGINS-TASK-DEPS-006.3:** An entry not redacted under `REQ-PLUGINS-TASK-DEPS-003` shall carry enough to render a node without reading the end as a task; a consumer needing the full task reads it by id or lists with `include_archived=true`. - **AC-PLUGINS-TASK-DEPS-006.4:** An edge whose end no longer exists as a task shall be omitted from `depends_on` and `blocks`, and shall not contribute to `blocked` or `blocked_reason`. This differs from the redaction in `AC-PLUGINS-TASK-DEPS-003.2`, which keeps an entry for a task that exists but is outside the caller's scope. - **AC-PLUGINS-TASK-DEPS-006.5:** No entry of `depends_on` or `blocks` shall report a *non-empty* status value outside the closed vocabulary in `AC-PLUGINS-TASK-DEPS-001.6`, including for an end whose task row is absent. The derivation's internal `missing` marker shall never reach either list. An empty status is required on a `blocks` entry by `AC-PLUGINS-TASK-DEPS-001.7` and is not a vocabulary violation there; on a `depends_on` entry it is one, because `AC-PLUGINS-TASK-DEPS-001.6` requires exactly one of the three values. ## Out of scope - **A flag reporting that an entry was redacted.** Excluded by `AC-PLUGINS-TASK-DEPS-003.7`: a false value on such a flag invites reading as an authority statement, and what it carries is diagnostic only. - **Admitting an end by reading it.** Excluded by `AC-PLUGINS-TASK-DEPS-003.3`, which bounds the admission test to data the response already holds so it cannot conflict with the query bound in `AC-PLUGINS-TASK-DEPS-004.1`. The cost is accepted under `AC-PLUGINS-TASK-DEPS-003.8`: repository and session scope under-admit, and an end the canvas could fetch directly may still be redacted. - **Page-stable redaction.** Under `AC-PLUGINS-TASK-DEPS-003.8` a repository- or session-scoped canvas admits an end only when the same response returns it, so the same edge end may carry a title at one page size and not another. The rule fully determines each response; no criterion requires the outcome to be stable across requests. - **Redaction on the event stream.** The canvas event projection has no per-entry scope evaluation, so the dependency projection is kept off events entirely by `AC-PLUGINS-TASK-DEPS-005.1` rather than redacted there.