#128: Define the ecosystem opportunity ranking contract

CONTEXT.md

@@ -20,6 +20,10 @@ _Avoid_: candidate, lead, alert
 The global, versioned catalog of reusable security concepts and source-backed relationships used for retrieval, classification, and strategy. It never owns project observations, evidence, assertions, or findings.
 _Avoid_: Investigation Graph, project graph, fact database
 
+**Ecosystem Signal**:
+An immutable, source-backed measurement about a reusable repository, package, release, configuration, or ecosystem subject used for opportunity ranking. It never claims that a project Target is vulnerable.
+_Avoid_: Research Observation, Finding, risk score, target fact
+
 **Knowledge Concept**:
 A reusable security subject with one stable lowercase `namespace:value` ID, one controlled kind, typed external identifiers, and source references. Weaknesses, attack patterns, techniques, controls, protocols, tools, commands, and standards are Knowledge Concepts.
 _Avoid_: project fact, finding, copied taxonomy row

docs/architecture.md

@@ -138,6 +138,8 @@ The pinned `@mastra/lance` package carries a local patch for three adapter defec
 
 The explicit Security Knowledge Graph remains in SQLite for versioned, reusable concepts; controlled predicates; source-backed relationships; typed external identifiers; tool I/O; tool groups; group membership; and weighted tool relationships. Reusable IDs use lowercase `namespace:value` keys. Seed publication synchronizes the owned catalog revision so renamed or retired seed edges do not survive indefinitely. `knowledge_tool_groups`, `knowledge_tool_group_members`, and `knowledge_tool_relationships` are seeded from curated common-shell transitions plus existing `docs/tools/*` `category` and `related_tools` frontmatter. Eval scoring treats a relationship match as positive sequence-coherence evidence; a missing edge remains unmodeled rather than becoming an exclusive allowlist failure. Skill Markdown chunking and semantic document retrieval use Mastra RAG, while deterministic keyword and concept-graph traversal remain local and explicit.
 
+Pinned global source snapshots may yield immutable Ecosystem Signals for opportunity ranking. Ranking applies license, revision, reproducibility, disclosure, isolation, egress, reset/teardown, and authorization-readiness gates before arithmetic; missing evidence holds a candidate instead of becoming zero. Eligible candidates are ordered only inside comparable cohorts using the published seven-dimension vector. The total never appears without its contributions, confidence, source-signal references, and unweighted change/disclosed-history overlays, and it never asserts that a project Target is vulnerable. Selecting a candidate is the boundary that creates project-owned Targets and subsequent Research Observations; global signals themselves never cross into project memory as deployed-target facts.
+
 The project Investigation Graph is an assertion layer over existing records, not another owner of Targets, Artifacts, Findings, Research Observations, Tasks, Attack Paths, Tool Runs, messages, memory, or reusable security knowledge. A Research Observation preserves measured or directly seen behavior, structured inputs and outputs, measurements, external identifiers, versioned scores, actor, time, and precise citations before interpretation. The user-facing Research Map projects canonical records, cited threads and messages, external sources, reusable-concept references, current Investigation Assertions, and Research Priorities through one coherent relational snapshot. The write model resolves canonical records through project-local Investigation Entities and stores append-only Assertions, coordinate-only role-bearing Citations, and rule-versioned Derivations with ordered inputs. Evidence state (`observed`, `derived`, `proposed`, `contradicted`, or `rejected`) stays separate from assertion lifecycle (`current`, `withdrawn`, or `superseded`). Revision is an optimistic, transactional replacement that retains the predecessor and its citations. SQLite and PostgreSQL relational queries define correctness. See [ADR 0001](./adr/0001-investigation-graph-as-assertion-layer.md).
 
 A Research Priority is an unresolved, citation-backed current assertion ranked for follow-up. Its deterministic score weights objective relevance (25%), evidence gap (20%), expected information gain (20%), target importance (15%), inverse predicate cost (8%), inverse predicate risk (7%), and authorization readiness (5%). Authorization readiness comes from the durable target ledger. Deliberately turning a Research Priority into a Task uses the existing Task workflow and a unique assertion-task receipt; it never schedules work, creates an approval, runs a tool, or promotes a Finding.