feat(evidence): define schema-bound extraction contract

[seonghobae]

Partial implementation of #199.

Buyer-visible boundary

This branch starts the schema-bound extraction portion of the evidence-native replay track. The slice is deliberately deterministic and storage-neutral: a versioned extraction schema binds every typed field to explicit reviewed source channels and a deterministic normalization contract before any WARC persistence, PROV graph emission, browser capture, model interpretation, retention store, or replay runtime can claim authority.

Current exact state

• protected main: b05d5acca82b9d916ada2c8e82f59f92a89817e1;
• exact branch head: b35d739017aa5d361b605be48045be50b5a35f6f;
• the merge base is current protected main; GitHub reports the PR open, Ready, and mergeable;
• no qualifying independent formal approval is established. Devin/CodeRabbit COMMENTED reviews are not approval.

The branch was reconstructed onto the live protected base by another actor before this evidence refresh. The current branch/base relationship and exact-head evidence below were independently re-fetched; predecessor checks are not promoted.

Implemented contract

The implementation adds ExtractionSchema, ExtractionField, typed value/cardinality metadata, explicit source-channel admission, and typed ExtractionNormalizationRule in originweave-evidence. Existing fields default to Verbatim; callers may explicitly choose TrimTextWhitespace for text or Rfc3339Utc for timestamp fields. Type-incompatible normalization fails closed with InvalidNormalizationRule. Schema and field identifiers are bounded and grammar-validated; field collections are bounded; fields require at least one reviewed source channel; duplicate channels and duplicate field identifiers fail closed. Reviewed source channels are stored through a BTreeSet, so their public representation is canonical set order rather than caller order. Public ExtractionSchemaError implements deterministic Display and std::error::Error.

Cardinality and required status are one internally consistent presence contract. ExtractionCardinality::One is necessarily required; ZeroOrOne is necessarily optional; contradictory One/optional and ZeroOrOne/required declarations fail closed with typed InvalidCardinalityRequirement. Many remains explicitly free to be required or optional because this value-object boundary does not define a minimum collection item count. ADR 0106 records these semantics and preserves the authority boundary: schema construction does not grant browser, network, model, secret, storage, retention, disclosure, or governance authority.

Test-first repair lineage

The cardinality defect was reproduced before the production repair. Exact RED head c5a87a64d96b12ef0399b72cb7d0ede3bb7e33d6 failed CI run 32619683199, Rust-contract job 97145852556, because field_rejects_contradictory_required_cardinality_contracts observed that both contradictory declarations still returned Ok.

The canonical branch then added the typed cardinality/required check in ExtractionField::new_with_normalization, exact typed-error assertions, the public error-contract assertion, a positive Many/required case, and binding semantics in ADR 0106. Earlier valid findings were also repaired: neutral identifier error text, canonical source-channel set identity, ADR coverage, and doctoring traceability. All current inline review threads are resolved; informational identifier/cardinality notes do not create approval authority.

Exact-current verification

For unchanged exact head b35d739017aa5d361b605be48045be50b5a35f6f against protected main b05d5acca82b9d916ada2c8e82f59f92a89817e1:

• CI run 32797549586: success;
• Rust contracts job 97651820715: exact-head checkout, repository contracts, canonical formatting, workspace/all-target check, full tests, strict Clippy, and API documentation/rustdoc success on the repository Rust 1.97.1 baseline;
• Production coverage job 97651820781: success with exact owned-production function / line / region / branch coverage all 100%;
• exact coverage artifact 9545376338, exact-coverage-b35d739017aa5d361b605be48045be50b5a35f6f, digest sha256:12ea3adc9a24216138c131f09d7eb3a8f31aaece2d44699bf31ee844f10eb91b;
• SAST Semgrep run 32797549659: success;
• Security Scan run 32797549579: success;
• fresh submitted reviews are COMMENTED only; no qualifying independent approval is established; and
• fresh inline review-thread inventory is fully resolved.

No Manifest V3 result is claimed because the exact-head workflow inventory does not expose an applicable MV3 run. No predecessor, queued, skipped, cancelled, synthetic-merge, status-only, or model-only evidence is promoted as current proof.

Truth boundary

This slice establishes the schema/admission/normalization/error contract only. It does not provide capture persistence, WARC records, PROV graphs, extracted-value runtime validation, browser evidence binding, tenant retention, offline replay, model-output authority, or closure of #199. Those remain dependency-ordered slices.

No workflow, secret, governance, release, tag, publish, approval, or merge mutation is included.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 3884b600-e70a-4270-a0f1-85f52449af08

📥 Commits

Reviewing files that changed from the base of the PR and between 40988c3 and 61a89d7.

📒 Files selected for processing (8)

• CHANGELOG.md
• crates/originweave-evidence/src/extraction_schema.rs
• crates/originweave-evidence/src/lib.rs
• crates/originweave-evidence/tests/extraction_schema.rs
• crates/originweave-evidence/tests/extraction_schema_error_contract.rs
• crates/originweave-evidence/tests/extraction_source_channel_set.rs
• docs/adr/0106-provenance-evidence-model.md
• docs/doctoring.md

🚧 Files skipped from review as they are similar to previous changes (1)

• CHANGELOG.md

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

버전 관리형 ExtractionSchema 계약을 추가했습니다. 필드 타입, 카디널리티, 정규화 규칙 및 소스 채널을 정의합니다. 생성 단계에서 식별자, 중복, 필드 수, 버전 및 호환성을 검증합니다. 공개 API, 오류 계약, 테스트 및 문서를 추가했습니다.

Changes

추출 스키마 계약

Layer / File(s)	Summary
추출 필드 계약 crates/originweave-evidence/src/extraction_schema.rs, crates/originweave-evidence/tests/extraction_normalization.rs, crates/originweave-evidence/tests/extraction_source_channel_set.rs	필드의 값 타입, 카디널리티, 정규화 규칙, 소스 채널 및 접근자를 추가했습니다. 생성자는 호환되지 않는 정규화 규칙, 빈 채널 및 중복 채널을 거부합니다. 소스 채널은 중복 제거 후 정렬해 저장합니다.
스키마 생성 및 공개 crates/originweave-evidence/src/extraction_schema.rs, crates/originweave-evidence/src/lib.rs, crates/originweave-evidence/tests/extraction_schema.rs	버전과 필드 목록을 보유하는 ExtractionSchema를 추가했습니다. 식별자 형식과 길이, 필드 수, 빈 목록, 중복 필드 및 카디널리티 조합을 검증합니다. 관련 타입과 제한 상수를 crate 루트에서 재내보냅니다.
오류 계약 검증 crates/originweave-evidence/src/extraction_schema.rs, crates/originweave-evidence/tests/extraction_schema_error_contract.rs, CHANGELOG.md	ExtractionSchemaError에 결정적 Display와 표준 Error 구현을 추가했습니다. 모든 오류 변형의 메시지와 비연쇄 오류 상태를 테스트하고 변경 기록에 계약을 추가했습니다.
스키마 운영 규칙 docs/adr/0106-provenance-evidence-model.md, docs/doctoring.md	One·ZeroOrOne과 필수 여부의 호환성 규칙을 기록했습니다. ExtractionSchema의 타입, 카디널리티, 정규화 및 검토된 소스 채널 계약과 권한 경계를 문서화했습니다. 참고문헌 표기도 수정했습니다.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Merge Risk: ⚪ Minimal · up to 61a89

This PR adds a deterministic, schema-bound extraction contract without changing runtime capture or persistence behavior. The current head passes the listed checks, and no actionable merge-blocking risk remains beyond normal review.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	Docstring check was indeterminate for this PR — some files could not be analyzed in time. Not blocking.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	PR 제목은 originweave-evidence에 스키마 기반 추출 계약을 정의하는 이번 변경의 핵심을 정확하고 간결하게 요약합니다.

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/extraction-schema-contract

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.