Documentation Monitoring & Semantic Diff

When “the page changed” is not proof that the lesson changed

A provider documentation page returns a new ETag and Last-Modified value. The navigation HTML was redesigned, but a cited paragraph also changes a retry limit from 3 to 5. If an updater reacts to every byte/hash change, it creates review noise. If it trusts only a timestamp or URL, it can miss a claim-affecting change.

This lesson builds Documentation Change Detection & Semantic Review Contract v1. The contract records source identity, HTTP validators, conditional-fetch outcome, raw and normalized content identity, snapshot lineage, diff type, semantic class, affected claim IDs, severity, review state/owner, next check and provenance. A transport change is evidence that something about the representation changed; it is never automatically evidence that a learning claim changed.

Route orientation and ownership boundary

MKN-008 owns documentation monitoring and semantic-diff review. MKN-007 is the hard conceptual prerequisite. MKN-009 owns background scheduling, so this lesson does not define cron cadence, leases or retry scheduling. It also does not mutate a live source, search index or Lesson Bible.

Foundation learners receive the field map and one mixed-change scenario. Repair learners isolate the first contradictory/missing evidence dimension. Experienced learners must defend normalization, validator and claim-impact boundaries without turning a hash comparison or an AI summary into the semantic oracle.

Mental model: source registry → conditional fetch → validator evidence → normalization → diff → semantic classification → affected claims → review

Use this chain:

source identity → conditional request → fetch/304 evidence → raw snapshot → normalization profile → normalized identity → structural/semantic diff → affected claim mapping → severity → review/promote/hold → next check

The transport plane says whether the HTTP representation appears changed or can be reused. The content plane preserves raw and normalized snapshots. The semantic plane asks whether meaning relevant to a cited learning claim changed. The governance plane decides who reviews and whether any canonical learning artifact may change. Mixing these planes creates false positives and false confidence.

Foundation contract: seventeen auditable dimensions

source_id and canonical_locator identify what is monitored. etag and last_modified preserve validator evidence. fetch_status records what the conditional retrieval actually returned. content_hash fingerprints the fetched representation while normalized_hash fingerprints the chosen relevant-content normalization.

previous_snapshot_ref and current_snapshot_ref preserve lineage. diff_type explains what kind of change was observed. semantic_change_class states whether the change is claim-affecting, non-semantic, equivalent relocation, unknown, or no change. affected_claim_ids binds semantic change to concrete learning claims. severity, review_state, review_owner, next_check_at, and provenance make the result bounded and auditable.

A complete row is evidence, not an automatic promotion decision.

Deep explanation: FACT, INFERENCE and DESIGN must remain separate

HTTP validators — FACT. RFC 9110 defines validators such as ETag and Last-Modified for representation validation and conditional requests. Strong and weak validators have different comparison semantics; a weak validator is not an exact byte-equality certificate.

Pipeline interpretation — INFERENCE. Transport-level change and semantic learning change should be stored separately. A changed entity tag can be caused by markup, generated navigation, advertising, timestamps, or a meaningful paragraph edit. A normalization profile can reduce noise, but the normalized hash is still only identity under that profile—not proof of pedagogical equivalence.

MAKNOW policy — DESIGN. Semantic categories, affected-claim mapping, severity, reviewer ownership, HOLD states and promotion rules are local authority. External documentation can supply facts; it cannot grant permission to rewrite a Lesson Bible or freshness state.

Worked examples: mixed change, navigation-only churn, and equivalent relocation

Baseline mixed change. ETag and Last-Modified change, the raw hash changes, and normalization removes the redesigned navigation. The retry-limit paragraph still differs after normalization, so normalized_hash changes. The semantic classifier marks CLAIM_AFFECTING, maps MKN-008-DEMO-RETRY-LIMIT, sets severity=MAJOR, and routes the case to CLAIM_AFFECTING_CHANGE_REVIEW_REQUIRED. That state does not auto-update the lesson; it creates a bounded review obligation.

Navigation-only change. Raw hash and validator values change, but the relevant normalized content remains identical. The correct state is NON_SEMANTIC_CHANGE_REVIEW_REQUIRED. Labeling it claim-affecting just because the raw hash changed is rejected.

Transfer: new URL, same meaning. A second official source republishes identical relevant semantics under a redesigned page and a new canonical locator. Source identity and provenance are recomputed. The result can become SOURCE_RELOCATION_EQUIVALENCE_REVIEW_REQUIRED, but only from the new evidence; the baseline label is not reused as an oracle.

Failure modes that must fail closed

Hold when all validator evidence is absent, fetch failed, raw/normalized content identity or diff type is UNKNOWN, required snapshot references are missing or contradictory, semantic class is unknown after a relevant normalized change, claim-affecting change has no affected claim IDs, review state is missing/approving instead of bounded, review owner/provenance is missing, or the changed context reuses the baseline decision.

Also hold contradictory classifications: a row cannot say semantic_change_class=NONE/NON_SEMANTIC while simultaneously listing affected claim IDs and severity=MAJOR; and it cannot claim CLAIM_AFFECTING when normalized content is unchanged unless explicit independent semantic evidence justifies that unusual case. The lab treats these contradictions as evidence defects, not invitations to guess.

Alternatives and trade-offs: validators, normalization and semantic review

ETag-first conditional retrieval is efficient when a source provides stable tags, but a weak tag has different equality semantics. Last-Modified is widely useful yet time resolution and server quality can limit precision. Missing ETag does not force failure when other bounded evidence exists, but the contract should expose the degraded validator state.

Aggressive normalization reduces layout noise but can accidentally delete meaningful examples, code blocks, warnings or numeric limits. Minimal normalization preserves more content but creates more review noise. Semantic models/LLMs can help organize candidate differences, but they cannot be the hidden final oracle. High-impact claim changes require visible evidence and review ownership.

Experienced bridge: semantic diff is a provenance problem, not only a text-diff problem

For experienced engineers, treat each monitored snapshot as a content-addressed, provenance-bearing observation. Preserve both the raw representation identity and the normalization profile/version that produced the normalized identity. Otherwise a normalization-rule change can masquerade as a source change.

Semantic classification should be reproducible from visible excerpts/rules or human review records. If a model proposes affected claims, store that as candidate evidence, not as canonical authority. The safest pipeline can answer: what changed at transport level, what survived normalization, what learning claim might be affected, and who accepted that interpretation?

Guided and independent practice

1. Open the baseline and separate content_hash from normalized_hash. 2. Change only navigation markup and verify that raw identity changes without creating affected claim IDs. 3. Change a numeric retry limit inside a cited paragraph and require claim mapping plus severity. 4. Remove ETag while retaining Last-Modified; preserve a degraded-validator review state rather than inventing exact equality. 5. Remove both validators and explain why the monitor cannot claim conditional-validation evidence. 6. Move equivalent content to a new canonical locator and rebuild provenance.

For independent practice, remove the expected state and recompute from the seventeen visible fields and learner-visible gate rules.

Verification evidence: what a reviewer must be able to reproduce

A reviewer must be able to reconstruct the source identity, validator evidence, conditional-fetch status, raw/normalized identity, previous/current snapshot lineage, declared diff type, semantic class, affected claims, severity, review owner/state, next-check time and provenance. The reviewer should also be able to explain why a changed validator/hash alone did—or did not—change the learning claim.

The deterministic lab covers baseline claim change, navigation-only churn, false-positive semantic classification, numeric-limit change, unmapped affected claims, degraded/missing validators, fetch failure, unknown semantic class, missing owner/provenance, snapshot lineage defects, transfer relocation and forbidden baseline-oracle reuse.

Assessment and transfer: redesigned new URL with equivalent semantics

Assessment has four blocking parts: explain the owned boundary and one non-goal; build the baseline Contract; diagnose the navigation-only false positive; then recompute the transfer case where a second source republishes identical semantics under a redesigned page and new URL.

Transfer passes only when source/provenance and snapshot identity are rebuilt from the new context, while affected claim IDs remain empty for semantically equivalent relevant content. Copying the baseline decision label fails even if the copied label happens to be plausible.

References, freshness and authority boundary

RFC 9110 was rechecked on 2026-09-13 for validator fields, strong/weak semantics, ETag, Last-Modified, and conditional-request behavior. These are stable protocol semantics, but they should be requalified by 2027-01-15 or earlier on material standards change.

Normalization rules, semantic classes, claim-impact severity and MAKNOW promotion/HOLD states are DESIGN authority, not RFC requirements. The lesson intentionally keeps that boundary visible.