# C5 SYNC SERVICE — CONTRACT & STATE MACHINE (C5A) + FORGEJO POLLING & CHANGE DETECTION (C5B)

**Phase:** C5A (Contract & State Machine) + C5B (Forgejo Polling & Change Detection)
**Status:** C5A = DONE · C5B = DONE (Polling & Change Detection) — **INAKTIV, NO-WRITE**
**Architektur:** FORGEJO MASTER → C5 SYNC SERVICE → TOLARIA DERIVED → SEARCH FULL REBUILD

C5A implementiert **ausschließlich** den Contract + die Sync State Machine + die
persistente Progress-State-Struktur. C5B baut darauf die **Forgejo Polling &
Change Detection Engine** (read-only). Beide sind **deterministische, inaktive
Python-Libraries + CLI + Testsuite** — sie führen **keine** externen Writes aus.

---

## NO-WRITE GUARANTEE (verbindlich, C5A + C5B)

C5A + C5B können **NOCH NICHT**:
- Tolaria schreiben
- Search rebuilden
- Forgejo schreiben
- produktiv pollen (kein Poll-Daemon)
- Netzwerk-Mutationen ausführen

**C5A** hat **keine** Netzwerk-/HTTP-/Socket-/Subprocess-Mutationsfunktionen
(`assert_no_write_guarantee()`).

**C5B** führt **ausschließlich read-only git-Befehle** gegen den lokalen Clone aus
(strikte Whitelist: `rev-parse`, `log`, `show`, `diff-tree`, `ls-tree`,
`cat-file`, `merge-base`, `rev-list`, `diff`). Jeder Write-Befehl
(`push`/`commit`/`add`/`reset`/`checkout`/`merge`/`rebase`) wird mit
`GitWriteBlockedError` blockiert. Die No-Downstream-Write-Guarantee wird statisch
per `assert_no_downstream_write()` bewiesen (keine HTTP-Mutationsimporte, keine
`/api/vault/save`-/`/api/search/rebuild`-Endpoints im Code, keine Git-Write-Befehle
in der Whitelist) und durch den Test `test_no_downstream_write` abgesichert.

---

## C5B — FORGEJO POLLING & CHANGE DETECTION ENGINE

### FORGEJO_READ_METHOD
**A) lokale Git-Mirror/Clone-Analyse** (bevorzugt).
- **AUTH_REQUIREMENT:** KEIN (read-only gegen lokalen Clone; kein Write-Token)
- **NETWORK_DEPENDENCY:** KEIN (lokale `.git`-Objekte; kein HTTP)

### POLLING_MODEL
- **Default:** 60 Sekunden
- **Environment-konfigurierbar:** `C5_POLL_INTERVAL_SECONDS` (z.B. `=120`)
- C5B implementiert die **Polling-Logik**, startet aber **KEINEN** dauerhaften
  Produktions-Daemon. Tests führen einzelne kontrollierte `poll_once`-Zyklen aus.

### HEAD_DISCOVERY
`get_current_head()` → Commit-SHA + parent/timestamp/message. Bei nicht
erreichbarem Forgejo: `RC_FORGEJO_UNAVAILABLE`, kein State-Fortschritt.

### COMMIT_RANGE_MODEL
Aus `last_seen_commit` (C5B-Baseline) bis HEAD deterministisch alle fehlenden
Commits in chronologischer (parent-korrekter) Reihenfolge. Kein Überspringen,
keine Doppelerfassung. Merge-Commits werden explizit behandelt (alle Parents).
Divergenz/History-Rewrite wird erkannt.

> **Wichtig:** C5B-Baseline ist `last_seen_commit`. `last_applied_commit` bleibt
> laut C5A-Contract für die spätere Propagation (C5C) reserviert und wird von C5B
> **NIE** fortgeschrieben.

### HISTORY_SAFETY
Wenn `last_seen_commit` kein Ancestor von HEAD ist: **FAIL CLOSED**
(`RC_OUT_OF_ORDER_COMMIT`). Keine automatische Rebase-/Reset-Logik.

### DIFF_MODEL
Für jeden neuen Commit: `git diff-tree -r --name-status -M -C --root` →
`ADDED` / `MODIFIED` / `DELETED` / `RENAMED` / `MOVED`. Bei unsicherer
Rename-Detection wird **nicht geraten** — Ambiguität wird sauber klassifiziert
(Human Review).

### KNOWLEDGE_SCOPE_MODEL
Nicht jede Forgejo-Datei ist automatisch Tolaria-Knowledge:
- **IN_SCOPE:** Markdown im Repo-Root ODER unter `notes/trading/system-docs/`
- **OUT_OF_SCOPE:** `tolaria/`, `a2-5/`, `red-queen-architecture/`,
  `notion-safety-brain/`, `notion-command-center/`, `backup_patches/`,
  `notes/reference/`, Nicht-Markdown, Build-Artefakte
- **LEGACY_SPECIAL:** `README.md` (x2, KEEP_DISTINCT) + `vps.md` (DEFERRED)
- **HUMAN_REVIEW:** Knowledge-Objekt ohne gültige `object_id`

Keine Secrets/Build-Artefakte in Sync-Change-Sets. Nicht blind `.md` = Sync.

### OBJECT_ID_MODEL
`object_id` wird **aus dem Frontmatter** gelesen (`id: object/<FULL_UUID>`),
nicht aus dem Pfad erzeugt, nicht neu generiert, nicht geraten. Ohne gültige ID:
`UNKNOWN_OBJECT_ID` / `UNKNOWN_LEGACY_OBJECT` → Human Gate.

### HASH_MODEL
- **`content_hash`:** SHA-256 des fachlichen Bodies (nach Frontmatter)
- **`metadata_hash`:** SHA-256 der relevanten Knowledge-Schema-Metadaten
  (`id`, `type`, `role`, `representation`, `state`, `derived_from`, `tags`,
  `knowledge_schema`). Pfad ist separat.
- Deterministisch und testbar.

### CHANGE_CLASSIFICATION
Aus Before/After deterministisch: `CREATE`, `CONTENT_UPDATE`,
`METADATA_UPDATE`, `STATE_UPDATE`, `RENAME`, `MOVE`,
`SOURCE_CANONICAL_RELATION_UPDATE`, `TAGS_UPDATE`, `SUPERSEDE`,
`DELETE_REQUEST`. Bei mehreren geänderten Aspekten in EINEM Objekt werden
**mehrere ObjectChange-Einträge** erzeugt (keine Information verloren).

### RENAME_MOVE_MODEL
Rename/Move nur automatisch, wenn **gleiche `object_id`** + eindeutige
Git-/Content-Evidence. ID bleibt stabil. Rename = Dateiname geändert (gleiches
Verzeichnis); Move = Verzeichnis geändert. Bei Ambiguität: Human Gate.

### DELETE_MODEL
Git-Delete wird **NIEMALS** zu automatischem Hard Delete. C5B erzeugt
`DELETE_REQUEST` → C5A führt es in Human Review. Keine Tolaria-Aktion.

### PAIR_MODEL
Wenn Root/source + canonical gemeinsam verändert werden, erkennt C5B die
Pair-Beziehung (`derived_from`). Ordnung für spätere C5C: Source zuerst,
Canonical danach. Noch nicht propagiert — Output enthält genug Information für
C5C.

### SECRET_SAFETY
C5B schreibt **keine** Secret-Inhalte in Logs/SQLite/Evidence. Bei
Secret-/Forbidden-Dateien: nur sichere Metadaten (`path`, `reason_code`,
`commit_sha`). Enthält ein Knowledge-Dokument einen möglichen Secret-Wert:
`RC_SECRET_DETECTED` FAIL CLOSED. Kein Wert wird ausgegeben.

### C5A_INTEGRATION
C5B speist gefundene Commits + ObjectChanges in den C5A Store ein (nur
State/Persistence, kein Network Write downstream). Flow: Poll once → discover
commits → classify changes → register commit → add object changes → Status
`DISCOVERED`/`VALIDATING` (bzw. `HUMAN_REVIEW_REQUIRED`). **Nicht** weiter zu
`PROPAGATING_TOLARIA`.

### OBSERVABILITY
C5B erweitert sichere Statusdaten: `last_seen_commit`, `poll_timestamp`,
`commits_discovered`, `objects_discovered`, `out_of_scope_count`,
`last_poll_status`, `last_poll_error_code`. Keine Content-Logs.

---

## State Machine (C5A)

### Normalzustände
`DISCOVERED → VALIDATING → READY → PROPAGATING_TOLARIA → VERIFYING_TOLARIA → UPDATING_SEARCH → VERIFYING_SEARCH → APPLIED`

### Fehlerzustände
`RETRY_PENDING`, `FAILED`, `DEAD`, `HUMAN_REVIEW_REQUIRED`

### Ordering
`WAITING_FOR_PREDECESSOR` — Commits werden nur in korrekter Reihenfolge
verarbeitet (`parent_sha` / `last_applied_commit`). Lücken werden **nicht**
übersprungen.

### Kerninvariante
**`last_applied_commit` wird NUR nach vollständigem Tolaria+Search PASS
fortgeschrieben** (`mark_applied` wird nur nach `VERIFYING_SEARCH → APPLIED`
aufgerufen).

---

## Commit Contract

Eine Verarbeitungseinheit = **ein Forgejo Commit**:

| Feld | Beschreibung |
|---|---|
| `commit_sha` | Primärschlüssel |
| `parent_sha` | Vorgänger (Ordering) |
| `discovered_at` | Zeitstempel |
| `sequence` | Reihenfolge |
| `status` | Sync-Zustand |
| `retry_count` | Retry-Zähler |
| `last_error` / `last_error_code` | Fehler + Reason Code |
| `created_at` / `updated_at` | Zeitstempel |

### Pro Changed Object
`object_id`, `path_before`, `path_after`, `operation`, `content_hash_before`,
`content_hash_after`, `metadata_hash_before`, `metadata_hash_after`,
`representation`, `state`

---

## Operation Model

`CREATE`, `CONTENT_UPDATE`, `METADATA_UPDATE`, `STATE_UPDATE`, `RENAME`, `MOVE`,
`SOURCE_CANONICAL_RELATION_UPDATE`, `TAGS_UPDATE`, `SUPERSEDE`, `DELETE_REQUEST`

**`DELETE_REQUEST` bleibt Human-Gate** — kein automatisches Hard Delete.

---

## Idempotenz

Basis: **`commit_sha + object_id + operation`** + Hash-Checks.

| Ergebnis | Bedeutung |
|---|---|
| `ALREADY_APPLIED` | Commit bereits vollständig angewendet |
| `ALREADY_AT_TARGET` | Ziel-Hash bereits erreicht |
| `RETRY_SAFE` | Noch nicht angewendet, sicher zu verarbeiten |
| `CONFLICT` | Existiert, aber Hash weicht ab |

Doppelte Commit-Erkennung ist **deterministisch**.

---

## Ordering

Commits nur in korrekter Reihenfolge. Fehlender Vorgänger → `WAITING_FOR_PREDECESSOR`
(Reason Code `OUT_OF_ORDER_COMMIT`). Nach Anwendung des Vorgängers wird der
Commit erneut validiert.

---

## Failure / Retry State

- `max_retries = 5` (konfigurierbar)
- Backoff: `1 / 2 / 4 / 8 / 16` Sekunden (gekappt)
- Nach Max → `DEAD` oder `HUMAN_REVIEW_REQUIRED`
- **Kein Endlos-Retry**

---

## Persistence

SQLite (`c5a.db`), isoliert, restart-fest. Anforderungen erfüllt:
- **atomic** (SQLite-Transaktionen, WAL)
- **restart-safe** (neuer Store auf gleicher DB behält State)
- **inspectable** (CLI `health`, `list-commits`, `commit-status`)
- **backupbar** (einzelne Datei)
- **keine externe DB** nötig
- **kein Trading-/Forgejo-DB-Coupling** (eigene DB)

---

## Bootstrap State

`UNINITIALIZED → RECONCILING → BASELINE_READY → ACTIVE`

Baseline darf **nur** aus `BASELINE_READY` gesetzt werden (Master↔Tolaria-
Reconciliation muss sauber sein). In C5A wird **keine produktive Baseline**
gesetzt.

---

## Reason Codes (geschlossene Menge)

`UNEXPECTED_TOLARIA_DRIFT`, `ID_COLLISION`, `UNKNOWN_OBJECT_ID`, `INVALID_SCHEMA`,
`DANGLING_DERIVED_FROM`, `AMBIGUOUS_DELETE`, `UNKNOWN_LEGACY_OBJECT`,
`AUTH_FAILURE`, `SEARCH_REBUILD_FAILURE`, `TOLARIA_UNAVAILABLE`,
`FORGEJO_UNAVAILABLE`, `OUT_OF_ORDER_COMMIT`, `SECRET_DETECTED`

Kein freier String-Wildwuchs als einziges Fehlerformat — unbekannte Reason Codes
werden abgelehnt (`InvalidReasonCodeError`).

---

## Security Boundary (dokumentiert, NICHT implementiert)

- **Forgejo credential:** READ ONLY (C5A hält keinen Forgejo-Write)
- **Tolaria write:** nur später C5 Service
- **Search rebuild:** nur C5 Service Token
- **Agents:** keine direkten Tolaria-/Search-Admin-Writes
- **Netzwerk-Härtung** wird später beim Deployment umgesetzt, NICHT jetzt

---

## Health Contract

`status`, `bootstrap_state`, `last_seen_commit`, `last_applied_commit`,
`pending_commits`, `failed_commits`, `dead_commits`, `human_review_required`,
`forgejo_status`, `tolaria_status`, `search_status`, `drift_count`,
`last_success_at`, `last_error_code`

C5A führt **keine echten externen Health-Probes** aus (rein State-Machine) —
`forgejo_status`/`tolaria_status`/`search_status` sind `UNKNOWN`.

---

## CLI

```bash
export C5A_DB=/path/to/c5a.db   # default: ./c5a.db
export C5_REPO=/path/to/forgejo-clone   # default: .
export C5_POLL_INTERVAL_SECONDS=60      # default: 60

# C5A
python3 rq_c5a_cli.py health
python3 rq_c5a_cli.py bootstrap-state
python3 rq_c5a_cli.py bootstrap-transition --to RECONCILING
python3 rq_c5a_cli.py set-baseline --commit <sha>
python3 rq_c5a_cli.py ingest-commit --json <file>
python3 rq_c5a_cli.py process-commit --json <file>
python3 rq_c5a_cli.py list-commits [--status <s>]
python3 rq_c5a_cli.py commit-status --sha <sha>
python3 rq_c5a_cli.py no-write-check

# C5B (rq_c5_cli.py)
python3 rq_c5_cli.py poll-once            # ein kontrollierter Poll-Zyklus (read-only)
python3 rq_c5_cli.py show-pending         # ausstehende Commits anzeigen
python3 rq_c5_cli.py show-commit <sha>    # Details eines Commits anzeigen
python3 rq_c5_cli.py dry-run-diff <sha>   # Diff eines Commits anzeigen (read-only)
python3 rq_c5_cli.py health               # Health-Contract anzeigen
python3 rq_c5_cli.py no-write-check       # No-Downstream-Write-Guarantee pruefen
```

**Kein** `daemon`/`start-forever`-Befehl in C5B — der produktive Poll-Daemon kommt
erst beim Deployment (C5).

---

## Tests

```bash
python3 test_c5a.py   # 25 PASS / 0 FAIL
python3 -m unittest test_c5b -v   # 39 PASS / 0 FAIL
```

**C5A** abgedeckte Fälle: normal commit lifecycle, multi-object commit, duplicate
commit, already-applied, out-of-order commit, missing predecessor, retry
progression, max retry → DEAD, human gate transition, restart/reload persistence,
state corruption handling, idempotency, delete request → human gate, dangling
relation → human gate, unexpected drift → human gate, no-write guarantee, bootstrap
lifecycle, baseline-only-from-BASELINE_READY, reason codes closed set, operations
closed set, health contract fields, last_applied-only-after-full-pass, retry
available bound, backoff sequence, invalid reason code rejected.

**C5B** abgedeckte Fälle: head discovery, single commit, multi commit, added
knowledge object, content update, metadata update, state update, tags update,
relation update, rename, move, delete request, out-of-scope file, legacy object,
unknown ID, secret detection, duplicate poll, lost poll, ordering, Forgejo
unavailable, history divergence, C5A persistence integration, no downstream write,
poll interval config.

---

## Dateien

- `rq_c5a.py` — C5A Kern-Library (Store + State Machine + No-Write-Check)
- `rq_c5a_cli.py` — C5A CLI
- `test_c5a.py` — C5A Testsuite (25 Tests)
- `rq_c5b.py` — C5B Kern-Library (GitReader + Scope + Classifier + Poller + No-Downstream-Write-Check)
- `rq_c5_cli.py` — C5 CLI (C5A + C5B: poll-once, show-pending, show-commit, dry-run-diff, health, no-write-check)
- `test_c5b.py` — C5B Testsuite (39 Tests)
- `README.md` — diese Datei