# 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.