Verify Doctor against the declared official API contract #301

Merged

erik merged 1 commit from fix/task-299c29f2-doctor-contract into main

2026-10-13 16:20:42 -05:00

erik commented

2026-10-13 16:15:01 -05:00

Owner

Doctor could report success after checking only OpenAPI shape and four bootstrap paths, even when a site omitted the official GET /sources search parameter. It now resolves the site's explicit contract identity against the immutable Slugkit.com archive, verifies the reference digest, and compares operations and reachable schemas with actionable failures.

The documented policy permits compatible additions while rejecting missing declarations and changes that prevent a standard client from working. Public reference requests omit site credentials, reject redirects, and enforce time, size, and comparison limits. Legacy/unknown declarations and unavailable references fail explicitly; package versions do not substitute for a contract version.

Validation: ./scripts/pre-pr.sh passed (build, generated CSS, formatting, lint, types, complete local tests; CLI 564 tests). Focused tests cover the missing source-search declaration, matching and additive contracts, breaking inputs/responses, identity/digest failures, unavailable references, recursive/external references, and credential isolation. The new checker also passed against the deployed Slugkit.com contract and its actual official archive.

Task: task-299c29f2 — Doctor misses mismatches with the published API contract.

Doctor could report success after checking only OpenAPI shape and four bootstrap paths, even when a site omitted the official GET `/sources` search parameter. It now resolves the site's explicit contract identity against the immutable Slugkit.com archive, verifies the reference digest, and compares operations and reachable schemas with actionable failures. The documented policy permits compatible additions while rejecting missing declarations and changes that prevent a standard client from working. Public reference requests omit site credentials, reject redirects, and enforce time, size, and comparison limits. Legacy/unknown declarations and unavailable references fail explicitly; package versions do not substitute for a contract version. Validation: `./scripts/pre-pr.sh` passed (build, generated CSS, formatting, lint, types, complete local tests; CLI 564 tests). Focused tests cover the missing source-search declaration, matching and additive contracts, breaking inputs/responses, identity/digest failures, unavailable references, recursive/external references, and credential isolation. The new checker also passed against the deployed Slugkit.com contract and its actual official archive. Task: task-299c29f2 — Doctor misses mismatches with the published API contract.

erik added 1 commit

2026-10-13 16:15:01 -05:00

fix: verify doctor against the declared official API contract

CI / build-lint-test (pull_request) Successful in 58s

Details

ede15f9eed

Task: #task-299c29f2

erik commented

2026-10-13 16:17:13 -05:00

Author

Owner

Independent review

PR: Slugkit #301 — open, reviewed head ede15f9eedb158fecaac6a98a6bc8e192b7da11c.
Verdict: approved. Blocking issues: 0. Warnings: 0.
Summary: Doctor resolves the selected site's explicit contract against the official exact-version archive, verifies identity and digest, and checks operation declarations and reachable local references. Input constraints and response guarantees are checked in their respective directions. Compatible additions are permitted under the documented conservative structural policy; missing official optional declarations still fail. External references are rejected without fetching, and official reference requests omit management credentials and reject redirects.
Acceptance criterion 1: met — authoritative source, exact-version resolution, and legacy/unknown behavior are explicit.
Acceptance criterion 2: met — documented minimum-interface policy distinguishes compatible additions from missing declarations and incompatible constraints.
Acceptance criterion 3: met — concrete path/method/parameter/schema diagnostics fail conformance; unavailable and unverifiable references fail explicitly.
Acceptance criterion 4: met — focused coverage includes matching contracts, missing source search, additions, breaking inputs/responses, unknown/unavailable references, recursive refs, digest failures, and credential isolation.
Acceptance criterion 5: met — Doctor remains read-only; external reference requests have a fixed public origin, omitted credentials, redirect rejection, and time/size limits.
Verification: parent verified exact-head CI run 522, full local checks with 1,261 tests, and seven passing Doctor checks against the live site. Reviewer inspected the implementation and focused tests without rerunning broad checks.
Next: wait for explicit human merge approval. Review establishes advertised contract compatibility, not live endpoint behavior or general JSON Schema equivalence.

### Independent review - PR: [Slugkit #301](https://forge.caradoc.com/erik/slugkit/pulls/301) — open, reviewed head `ede15f9eedb158fecaac6a98a6bc8e192b7da11c`. - Verdict: approved. Blocking issues: 0. Warnings: 0. - Summary: Doctor resolves the selected site's explicit contract against the official exact-version archive, verifies identity and digest, and checks operation declarations and reachable local references. Input constraints and response guarantees are checked in their respective directions. Compatible additions are permitted under the documented conservative structural policy; missing official optional declarations still fail. External references are rejected without fetching, and official reference requests omit management credentials and reject redirects. - Acceptance criterion 1: met — authoritative source, exact-version resolution, and legacy/unknown behavior are explicit. - Acceptance criterion 2: met — documented minimum-interface policy distinguishes compatible additions from missing declarations and incompatible constraints. - Acceptance criterion 3: met — concrete path/method/parameter/schema diagnostics fail conformance; unavailable and unverifiable references fail explicitly. - Acceptance criterion 4: met — focused coverage includes matching contracts, missing source search, additions, breaking inputs/responses, unknown/unavailable references, recursive refs, digest failures, and credential isolation. - Acceptance criterion 5: met — Doctor remains read-only; external reference requests have a fixed public origin, omitted credentials, redirect rejection, and time/size limits. - Verification: parent verified exact-head CI run 522, full local checks with 1,261 tests, and seven passing Doctor checks against the live site. Reviewer inspected the implementation and focused tests without rerunning broad checks. - Next: wait for explicit human merge approval. Review establishes advertised contract compatibility, not live endpoint behavior or general JSON Schema equivalence.

erik merged commit 3c061340ef into main

2026-10-13 16:20:42 -05:00

erik deleted branch fix/task-299c29f2-doctor-contract

2026-10-13 16:20:42 -05:00

erik referenced this pull request from a commit

2026-10-13 16:20:43 -05:00

Merge pull request 'Verify Doctor against the declared official API contract' (#301) from fix/task-299c29f2-doctor-contract into main