EKOSdocs
Docs / Concepts Learn

Entities

Objects are the things EKOS knows about: tables, services, files, functions, pipelines, people, documents.

An object (called an entity in conversation) has an id, a name, a kind, free-form properties, evidence, and a creation time.

Built-in kinds cover common enterprise things — File, Directory, Table, Column, Dataset, Service, Api, Pipeline, Dashboard, Person, Model, Prompt, Agent, BusinessRule, BusinessConcept, Entity. Analyzers add custom kinds for language- or format-specific things (RustSymbol, PythonModule, JavaMethod, ModelTable, Procedure, View, Trigger, SchemaChange, Ticket, Document, Section, Risk, Rollup, …). Full list: Entity Types.

File-derived and live objects

Most objects are read from files: a CREATE TABLE in a script, a class in a source tree. A database declared in [[databases]] is also read live, from its catalog, and the objects it yields (Table, View, Procedure, Trigger) carry origin: live. The two are kept apart on purpose:

  • identity resolution never merges a live object with a file-derived one;
  • name lookups (which table a routine writes, which table a schema change touches) use a live object only for a name no file defines;
  • at commit, the code's claims are compared with the database, and each disagreement becomes a conflict — with an explanation where the source tree itself explains it, such as a migration not yet applied.

A table dropped from the database leaves the model after the next build and compile.

Identity

The same real thing often appears from several sources — a customers table in SQL, an ORM model in Python, a mention in a wiki. EKOS resolves identity conservatively:

  • exact normalized-name duplicates of the same source kind merge;
  • fuzzy matches whose names agree word for word become unconfirmed SameAs relationships awaiting human review — never a silent, irreversible merge;
  • objects identified by a structural key (a file path, a manifest directory) and objects read live from a database are never merge candidates;
  • cross-system candidates (e.g. an Informix cust_mstr vs. a Postgres customers) come from ekos identity scan and are likewise unconfirmed until reviewed.