Skip to content

A project entity has no valid edge to a document, so an implementation cannot be linked to the spec that introduced it #2579

Description

@oceanwaves630

Summary

A project entity has no valid edge to a document entity in any direction, so an
implementation cannot be linked to the specification that introduced it. Its two closest
siblings can: the ADR-002 base endpoint table carries Artifact introduced_by Document and
Service introduced_by Document, and Concept introduced_by Document besides. Project is the
one of the four that is missing the row.

Read at 57490469c, docs/adr/ADR-002-edge-ontology.md. Every row whose source is Project:

| `Project` | `implements`    | `Concept` |
| `Project` | `competes_with` | `Project` |
| `Project` | `composed_with` | `Project` |

and every row whose target is Document:

| `Concept`  | `introduced_by` | `Document` |
| `Artifact` | `introduced_by` | `Document` |
| `Service`  | `introduced_by` | `Document` |
| `Document` | `supersedes`    | `Document` |
| `Document` | `derived_from`  | `Document` |
| `Document` | `precedes`      | `Document` |
| `Document` | `depends_on`    | `Document` |

How it shows up

An ingestion pass that records this repository's own structure hits it immediately. A pack is a
project; the ADR that specifies it is a document; "this pack implements that ADR" is the
single most common structural claim anyone would want to store about this codebase, and it is
unrepresentable. The edge is refused, and the honest options are to leave the structure unrecorded
or to mint a relation that says something else.

implements does not help in its current form either: it is Project → Concept and
Service → Concept, so it reaches the idea a pack realizes but not the document that specifies it.

What the fix probably is, and the part that needs a decision

Project introduced_by Document restores the symmetry with Artifact and Service and needs no
new relation, only a row. Before that lands, two questions are worth answering rather than
assuming:

  1. Is introduced_by the right claim for "specified by"? For Concept it reads as "this idea was
    introduced in that paper", which is the same shape.
  2. Document → Concept currently admits only instance_of, refutes and supports, so a
    document cannot depends_on a concept either. Whether that is deliberate or the same omission
    is worth stating in the same pass, because both were found by the same ingestion.

Pack-declared endpoint rules are additive (ADR-017), so a pack could add the row today without an
ADR. That is the wrong route for a base-taxonomy gap: the asymmetry is in the base contract and
the correction belongs there.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions