Initial curated RAGcore source from c16667f0c9397e2bfc8dd0255b114fba23c8d05e

2026-10-01 01:34:21 +02:00
commit 7ca726caf2
@@ -0,0 +1,51 @@
+# Connectors
+
+## V1
+
+### Upload
+Menselijke of API-upload. Vereist filename, content length en target space. Upload is nooit automatisch trusted.
+
+### Read-only folder
+Scant een expliciet gemounte root. Path traversal en symlinks buiten root worden geweigerd. De connector schrijft nooit naar de bronmap.
+
+### Git repository
+Leest een pinned commit/ref uit lokale checkout of toegestane remote. Registreert repository, commit, path en language. Secrets/binaries worden uitgesloten volgens policy.
+
+### Website/sitemap
+Optioneel late V1. Alleen expliciet toegestane domains, robots/politeness, size/time limits en SSRF-beveiligde fetcher.
+
+## Connector contract
+
+`scan(cursor) -> items + next_cursor`; `acquire(item) -> byte stream + metadata`; `fingerprint(item)`. Connectors bevatten geen parsing- of publicationlogica.
+
+## Deletion semantics
+
+Een volledige succesvolle scan mag ontbrekende items als source-deleted markeren. Een partiële/mislukte scan mag nooit massaal verwijderen.
+
+## Source Registry en synchronisatie (1.2.0)
+
+Iedere bron is een persistent record in `content.sources` (id, workspace, knowledge
+space, naam, type, status, secret-vrije configuratie, sync-state, laatste sync,
+laatste succesvolle sync, laatste revisie). Iedere ingest registreert zijn bron
+bij eerste gebruik; ad-hoc uploads zonder `source_id` horen bij de ingebouwde
+*Uploads*-bron van hun space (`upload_source_id(space_id)`, deterministisch).
+
+De `source_id` is **één identiteit** door de hele keten: document → chunk →
+Qdrant-payload → provenance → citation (`ragcore://source/<id>`) → `source_ids`-filter
+→ Control Plane. De `source_key`/`external_id`-dedupsleutel van documenten blijft
+ongewijzigd (sync-clients via de upload-API merken niets).
+
+Synchronisatie (`SourceSyncService`, worker-job `sync_source`, alleen folder/Git):
+
+```
+discover (alle pagina's) → vergelijk fingerprint met registry-items
+  → nieuw/gewijzigd: acquire → blob → ingest_upload-job (zelfde pipeline als uploads)
+  → ongewijzigd: niets
+  → verdwenen (alleen bij complete scan): document retiren
+  → persist run: discovered / new / changed / unchanged / removed / failed
+```
+
+Git-items krijgen het commit als `source_revision` op de documentversie; het
+stabiele document-id van een item is zijn pad (`locator`), niet `<commit>:<pad>`.
+Er is geen scheduler: een sync start vanuit de Control Plane ("Sync now") of door
+een `sync_source`-job te enqueuen. Website-bronnen zijn nog niet aan te maken.