From b4612cb795be09886136c349499b004bc1b69537 Mon Sep 17 00:00:00 2001 From: tegwick Date: Sun, 24 May 2026 15:35:41 +0200 Subject: [PATCH] Seeded with INTENT.md --- INTENT.md | 324 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 4 +- 2 files changed, 325 insertions(+), 3 deletions(-) create mode 100644 INTENT.md diff --git a/INTENT.md b/INTENT.md new file mode 100644 index 0000000..25d852f --- /dev/null +++ b/INTENT.md @@ -0,0 +1,324 @@ +# INTENT + +## Purpose + +This repository exists to provide the core domain engine for the **citation-evidence** ecosystem. + +**citation-engine** defines the stable conceptual model, service contracts, API boundaries, persistence interfaces, and citation rendering logic needed to manage documents, annotations, evidence items, evidence links, and reusable citation presentations. + +It is the domain center of the system. + +--- + +## Primary Utility + +The repository provides the shared engine that allows the other citation-evidence subsystem repositories to work against a common model. + +It should define and coordinate the core concepts: + +- **Document** +- **DocumentRepresentation** +- **Annotation** +- **Selector** +- **EvidenceItem** +- **EvidenceSet** +- **EvidenceLink** +- **CitationCard** +- **CitationRecoveryAttempt** + +The engine should make it possible to create, store, retrieve, relate, render, and export evidence-backed citations without depending on one specific viewer, frontend, storage backend, or document format. + +--- + +## Intended Users + +Primary users of this repository are developers and agents building the citation-evidence system. + +They include: + +- developers implementing the review workspace +- developers implementing evidence-backed form workflows +- developers implementing document ingestion and citation recovery +- developers implementing anchoring and re-anchoring logic +- developers integrating citation-evidence into other applications +- coding agents that need a stable model and API boundary for implementation work + +End users should usually experience this repository indirectly through applications built on top of it. + +--- + +## Strategic Role + +The strategic role of **citation-engine** is to prevent the citation-evidence ecosystem from becoming a loose collection of viewer-specific annotation tools. + +It provides the shared domain language that keeps the system coherent. + +The repository should ensure that: + +- annotations are not tied to one viewer implementation, +- evidence is treated as a first-class object, +- source passages can be reused across forms, claims, requirements, reports, and webpages, +- citation presentation is portable, +- storage and rendering implementations remain replaceable, +- subsystem repositories can evolve without breaking the core conceptual model. + +--- + +## Core Concept + +The engine models the central flow of evidence-backed citation work: + +```text +Document + → DocumentRepresentation + → Annotation + → EvidenceItem + → EvidenceLink + → CitationCard +```` + +A **Document** is the known source. + +A **DocumentRepresentation** is a normalized, searchable, addressable representation of that source. + +An **Annotation** is a technical mark on a source range. + +An **EvidenceItem** is the meaningful evidence object created from one or more annotations. + +An **EvidenceLink** connects evidence to a structured target such as a form field, claim, requirement, decision, or document section. + +A **CitationCard** is a portable rendering of evidence for use in webpages, Markdown, reports, or other documents. + +--- + +## Scope + +This repository should own: + +* the core domain model +* TypeScript interfaces and schemas for citation-evidence entities +* service contracts for documents, annotations, evidence, bindings, and citation rendering +* persistence interfaces +* event definitions +* citation card rendering contracts +* import/export contracts +* W3C Web Annotation mapping where practical +* orchestration-level use cases that combine domain objects + +It should provide the stable contracts consumed by: + +* **evidence-anchor** +* **evidence-source** +* **citation-work** +* **evidence-binder** +* **citation-evidence** + +--- + +## Out of Scope + +This repository should not own implementation details that belong to more focused subsystems. + +Specifically, it should not own: + +* PDF rendering internals +* viewer-specific selection capture +* low-level selector resolution algorithms +* fuzzy text matching implementations +* document parsing and ingestion pipelines +* OCR processing +* external source discovery implementations +* full review workspace UI +* form UI rendering +* visual guide overlay rendering +* application shell and deployment configuration + +Those responsibilities belong to the appropriate subsystem repositories. + +--- + +## Architectural Position + +The repository sits between the product shell and the specialized subsystems. + +```text +citation-evidence + integrated product shell + +citation-engine + core model, APIs, persistence contracts, citation rendering + +evidence-anchor + selector creation, resolution, re-anchoring, highlight contracts + +evidence-source + ingestion, extraction, metadata, source discovery, recovery + +evidence-binder + evidence-to-field / claim / requirement links + +citation-work + review workspace and annotation UX +``` + +The engine should define the contract, not dictate every implementation. + +--- + +## Design Principles + +### Viewer Independence + +The engine must not depend on one PDF viewer, Markdown renderer, HTML renderer, or frontend framework. + +Viewer-specific logic should be hidden behind adapters owned by other subsystems. + +### Evidence as First-Class Object + +Evidence must not be reduced to a highlight. + +An evidence item may include commentary, confidence, status, tags, and links to structured targets. + +### Selector Neutrality + +The engine should understand selectors as domain objects but should not own all selector resolution logic. + +Selector creation and resolution belong primarily to **evidence-anchor**. + +### Storage Replaceability + +The engine should define persistence interfaces that can be implemented by local files, SQLite, PostgreSQL, browser storage, or other storage backends. + +### Portable Presentation + +Citation rendering should support multiple output targets, especially: + +* internal web UI +* web components +* Markdown +* HTML +* later report/document exports + +### Standards Compatibility + +The engine should support mapping to W3C Web Annotation concepts where practical, but it does not need to use JSON-LD as the only internal representation. + +### Agent Readiness + +The model and APIs should be explicit, machine-readable, and suitable for agentic workflows. + +--- + +## Initial Domain Services + +The first implementation should likely define service contracts for: + +```text +DocumentService + create, get, update, list, attach representation + +AnnotationService + create, get, list by document, resolve status, update + +EvidenceService + create evidence item, attach annotation, update commentary, set status + +EvidenceBindingService + link evidence to target, list evidence for target, switch active evidence + +CitationRenderingService + render citation card as HTML, Markdown, or structured object + +ImportExportService + import/export internal model and W3C-compatible annotation data +``` + +These services may initially be interfaces and in-memory implementations only. + +--- + +## Initial Entity Set + +The first model version should include: + +```text +Document +DocumentRepresentation +Annotation +Selector +EvidenceItem +EvidenceSet +EvidenceLink +CitationCard +CitationTarget +CitationRecoveryAttempt +``` + +The first implementation does not need to be complete, but the naming should stabilize early to guide the other repositories. + +--- + +## Integration Expectations + +This repository should be easy to consume from other subsystem projects. + +Expected consumers: + +* **evidence-anchor** uses the selector and annotation types. +* **evidence-source** creates documents and document representations. +* **citation-work** creates annotations and evidence items through engine services. +* **evidence-binder** creates and manages evidence links. +* **citation-evidence** integrates the services into the reference workspace. + +The engine should avoid circular dependencies with these repositories. + +--- + +## First Useful Version + +A first useful version of **citation-engine** should provide: + +* core TypeScript types for the main domain objects, +* in-memory repositories for development and tests, +* basic services for creating documents, annotations, evidence items, and evidence links, +* a simple citation card renderer for Markdown and HTML, +* basic event types, +* initial W3C Web Annotation mapping notes or stubs, +* examples showing how the other subsystem repos should interact with the engine. + +--- + +## Success Criteria + +The repository is successful when another developer or coding agent can use it to understand and implement the core citation-evidence domain without guessing the central concepts. + +A first successful implementation should make it possible to: + +1. create a document, +2. attach a document representation, +3. create an annotation with selectors, +4. create an evidence item from the annotation, +5. link the evidence item to a target, +6. render the evidence as a citation card, +7. leave viewer-specific and ingestion-specific work to other subsystems. + +--- + +## Repository Character + +This repository should be: + +* domain-centered, +* stable but evolvable, +* implementation-light at first, +* strongly typed, +* explicit about boundaries, +* friendly to both humans and coding agents, +* suitable as the conceptual backbone of the citation-evidence ecosystem. + +--- + +## Guiding Statement + +**citation-engine exists to make evidence-backed citations a stable, reusable, and portable domain model.** + diff --git a/README.md b/README.md index fcd7b8f..800621f 100644 --- a/README.md +++ b/README.md @@ -1,3 +1 @@ -# repo-seed - -A git repository template to bootstrap coulomb projects from. \ No newline at end of file +Domain model and tooling for citations.