08 · Adapter / Source Coverage Design

Area 8 verdict: PARTIAL (P2). Coverage is strong (score 94, 15/16 sources COVERED) and the scanner fired 2026-06-05 04:10:01 CEST. Remaining: one PARTIAL source (kb_sop), no formal freshness policy on the contract, and partial/unknown behavior not propagated to the node.

---

1. Current adapter reality (live + checkpoint)

• v_rp_source_adapter_coverage score 94; 15/16 sources COVERED, staleness 0; only kb_sop_docs = LIVE_ADAPTER_PARTIAL (0.66d).
• 16 census sources [ckpt]: 10 DB LIVE_DB_FN + 6 host adapters (crontab/timers/dot_bin/scripts/docker/kb).
• wf_adapter_run_log 21 runs; scanner systemd timer wf-universal-scanner.timer fired 04:10:01 CEST success (T2-prior finding #9 resolved).
• dot_tools 309 = 186 EXECUTABLE_CONFIRMED + 19 helper + 4 missing + 100 registered-unconfirmed → dot_reconciliation_score=60.
• v_rp_uncovered_source_classes = 0 NEEDS_ADAPTER (denominator is KNOWN).

2. Does the coverage design support scale?

Source class	Adapter	Status	Scale-ready?
DB views/functions	10 LIVE_DB_FN	COVERED	yes
host crontab	adapter	COVERED	yes
systemd timers	adapter	COVERED	yes
filesystem (dot_bin/scripts)	adapter	COVERED	yes (186/287 mapped)
docker	adapter	COVERED	yes
KB / SOP	adapter	PARTIAL	no — needs full adapter
events	event_type_registry	COVERED	yes
queues	job_queue / Điều-45	COVERED (census)	partial — observe-heavy, actuate-light
runtime observations	pro_run_obs	COVERED	yes

Architecture is adapter-registry-based and scales (new source = new adapter row + scanner pass), but two design gaps remain:

1. No contract-level freshness policy — the node contract doesn't know if its feeding adapter is stale/partial.
2. Partial/unknown not propagated — kb_sop PARTIAL is in the coverage view but not on the affected nodes (ties to doc 05 PARTIAL_SOURCE flag).

3. Adapter registry design (formalize what exists)

workflow_discovery_source_registry + wf_adapter_run_log + workflow_scanner_registry already form the registry. Formalize per-source:

source_code, source_class (DB|HOST_CRON|SYSTEMD|FS|DOCKER|KB_SOP|EVENT|QUEUE|RUNTIME_OBS),
adapter_kind (LIVE_DB_FN|HOST_ADAPTER|...), coverage_status (COVERED|PARTIAL|MISSING|UNKNOWN),
last_scan_at, staleness_days, freshness_sla_days, on_partial_behavior, on_unknown_behavior

4. Freshness policy (the new design element)

Source class	freshness SLA	if exceeded
DB LIVE_DB_FN	real-time (per query)	n/a
host crontab/systemd/FS/docker	≤ 1 day (daily scanner)	mark STALE_ADAPTER, badge feeding nodes
KB/SOP	≤ 1 day	mark PARTIAL_SOURCE / STALE_ADAPTER
events/queues	≤ 1 day	mark STALE_ADAPTER

The scanner runs daily (04:10). Policy: a source whose last_scan_at is older than freshness_sla_days → coverage_status degrades to STALE; nodes fed by it get a STALE_ADAPTER/PARTIAL_SOURCE warning flag (doc 05). A partial/stale source is never counted as a total (the "partial-as-total 525" trap — trigger universe 525 is DB-only; host 77 not yet in the additive total).

5. Unknown / partial behavior (explicit)

• PARTIAL (kb_sop): count from this source is shown with PARTIAL_SOURCE flag + count_semantics=PARTIAL; never summed into a headline-safe total without the flag.
• UNKNOWN: a source class with no adapter → its objects are RP_NOT_VISIBLE (not silently 0). v_rp_uncovered_source_classes already enumerates this (currently 0).
• STALE: see §4.

6. Scanner automation requirements

• Daily systemd timer (LIVE) — keep; add a heartbeat/miss alert: if wf_adapter_run_log has no successful run in > SLA, raise a single guard row (no system_issues insert — that has a birth trigger; use a birth-free guard view, per prior-run gotcha).
• Per Điều-45 (queue law): the scanner is a job, not an event; the queue carries a signal, not data; the executor boundary holds (scanner is no-mutation discovery).
• Prove daily fire over a window (the prior run noted "0 on 06-05" for wf_scanner_run_log even though the adapter log fired — reconcile the two logs so "scanner fired" is unambiguous).

7. Classification

Issue	Class	Severity
kb_sop adapter PARTIAL	INFRA_INCOMPLETE	P2
No contract-level freshness policy / propagation	ARCHITECTURE_GAP	P2
Partial/stale source not flagged on node	DATA_DEBT	P2
Two scanner logs disagree (adapter fired, scanner_run 0)	OPERATIONAL_DEBT	P2
Queues observe-heavy / actuate-light (no drainers)	INFRA_INCOMPLETE	P3 (operator)

8. Required technical spec for T1 (Area 8)

1. Add freshness_sla_days + on_partial_behavior + on_unknown_behavior to the source registry; build v_rp_adapter_freshness (STALE/PARTIAL/COVERED per source with SLA check).
2. Propagate PARTIAL_SOURCE/STALE_ADAPTER onto node warning_flags for nodes fed by partial/stale sources (doc 05).
3. Reconcile wf_adapter_run_log vs wf_scanner_run_log into one v_rp_scanner_heartbeat (last successful end-to-end run + miss alert, birth-free).
4. Acceptance: kb_sop nodes carry PARTIAL_SOURCE; no PARTIAL count appears in a headline-safe total un-flagged; scanner heartbeat shows a successful run within SLA.