entity relationship model

docs/entity-relation-model.md

@@ -0,0 +1,54 @@
+# Entity And Relation Model
+
+`infospace-bench` owns the application-level semantic model for infospace
+entities and relation triplets. `markitect-tool` remains the Markdown structure
+provider and is accessed only through `infospace_bench.markdown_adapter`.
+
+## Entity Artifacts
+
+Entity artifacts are registered in `artifacts/index.yaml` with `kind: entity`
+and are stored under `artifacts/entities/`.
+
+The parser extracts:
+
+- `artifact_id`: manifest identity such as `entity/division.md`
+- `slug`, `title`, and `h1_raw`: identity derived from the document H1
+- `definition`, `source_chapter`, `context`, `domain`, `original_wording`,
+  and `modern_interpretation`: legacy-style sections where present
+- `h1_is_title_case`, `has_original_wording`, `definition_word_count`,
+  `total_word_count`, and ordered `section_slugs`: compatibility metrics used by
+  evaluation and inspection flows
+- `source_path`: path to the concrete artifact file
+
+`## Definition` is required. Missing required sections raise
+`invalid_entity_artifact` with a `missing_sections` detail list.
+
+## Relation Artifacts
+
+Relation artifacts are registered with `kind: relation` and are stored under
+`artifacts/relations/`.
+
+The parser extracts:
+
+- `artifact_id` and `slug`: manifest identity plus a relation slug derived from
+  the H1
+- `subject`, `predicate`, `object`: the relation triplet
+- `subject_slug`, `object_slug`, `subject_entity_id`, and `object_entity_id`:
+  endpoint links back to parsed entity artifacts
+- `relation_type`, `vsm_channel`, `evidence`, and `feedback_role`: semantic and
+  evaluation metadata
+- `is_feedback_member`: derived from whether `feedback_role` is present
+
+`## Subject`, `## Predicate`, and `## Object` are required. When relation
+listing is performed from an infospace manifest, subject and object slugs must
+resolve to entity artifacts or `unresolved_relation_endpoint` is raised.
+
+## CLI
+
+```bash
+python3 -m infospace_bench entities infospaces/bootstrap-pilot
+python3 -m infospace_bench relations infospaces/bootstrap-pilot
+```
+
+These commands emit JSON records for downstream evaluation, graphing, and
+inspection workflows.