Skip to content

Fold span grounding into EventMention (#170 / GAP-007) - #233

Merged
seonghobae merged 8 commits into
mainfrom
cursor/span-grounded-mentions-a17b
Aug 26, 2026
Merged

Fold span grounding into EventMention (#170 / GAP-007)#233
seonghobae merged 8 commits into
mainfrom
cursor/span-grounded-mentions-a17b

Conversation

@seonghobae

@seonghobae seonghobae commented Aug 25, 2026

Copy link
Copy Markdown
Contributor

Product slice

Issue #170 / GAP-007 asked for one calibrated TDT + CHRONOS product workflow. On current protected main (c482ccea), event_core already has isolated mention/instance types plus first-story FAR/miss, link P/R, tracking P/R, WindowDiff/Pk, schema-slot P/R, and CHRONOS Brier scoring.

The missing #170 contract implemented here is span-grounded EventMention:

  • EventMention is the only constructible mention type; there is no second unused mention type that can be built without a span
  • each mention cites one exact SourceSpan, document identity, six-clock evidence, extractor/model version, and proposed/reviewed status
  • surface text is the document substring at that span
  • availability after knowledge cutoff fails closed; delayed reporting at or before cutoff is kept
  • reviewed status is inspection, not instance promotion
  • link, track, instance, registry, and first-story consumers construct grounded mentions
  • exact-extent precision/recall recover known ACE extents (occupancy RMSE 0) and beat a whole-document extractor (RMSE 1)

This is not another identity gate and does not reimplement #226/#230/#231/#232/#239. Other-agent #235/#236/#237/#238/#240/#241 are left alone. psychometric_core and network_analysis are identical to origin/main. Workspace 0.2.0 versions are inherited from main. The EventMention CHANGELOG line stays under [Unreleased].

Remaining #170 work

Unified TDT/CHRONOS workflow composition, Allen/CHRONOS interval consistency, persistence, and versioned JSON/JSON-LD/GraphML exports.

Verification

  • Rebased onto origin/main c482ccea
  • cargo fmt -- --check is clean
  • cargo check --workspace --tests compiles
  • cargo test -p event_core passed
  • event_core authored LCOV: mention.rs 131/131, span_mention.rs 170/170, error.rs 147/147

Draft until exact-head TEPP product CI is green (Format/lint/test/rustdoc, production line/branch coverage, live-postgres, Repository contracts and Python branch coverage, Validate planning).

Sources

Doddington et al. (2004) ACE extent mapping; Allan (2002) detection-vs-instance; Jensen & Snodgrass (1999) availability vs event time. Numeric provenance: docs/doctoring/span-grounded-mentions.md.

Open in Web Open in Cursor 

Summary by CodeRabbit

  • 새 기능

    • 이벤트 멘션이 문서의 정확한 원문 범위와 증거 정보에 기반하도록 개선되었습니다.
    • 멘션의 검토 상태, 시간 증거, 추출기 버전을 확인할 수 있습니다.
    • 멘션 범위의 정밀도와 재현율을 계산할 수 있습니다.
    • 유효하지 않은 문서 범위, 시간 기준, 상태 및 메타데이터를 자동으로 거부합니다.
  • 문서

    • span 기반 멘션 계약, 평가 기준 및 관련 연구·아키텍처 문서가 추가·갱신되었습니다.
  • 버그 수정

    • 근거가 불충분한 멘션이 이벤트 인스턴스로 잘못 처리되지 않도록 검증이 강화되었습니다.

@coderabbitai

coderabbitai Bot commented Aug 25, 2026

Copy link
Copy Markdown

Review Change Stack

Warning

Review limit reached

Next included review available in 2 minutes.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 2e19b95d-7003-4141-9605-7a1b7efcb39a

📥 Commits

Reviewing files that changed from the base of the PR and between dfaac50 and 8086860.

📒 Files selected for processing (6)
  • ARCHITECTURE.md
  • CHANGELOG.md
  • docs/TRACEABILITY.md
  • docs/adr/README.md
  • docs/research/standards-and-literature.md
  • docs/validation/temporal-event-foundation.md
📝 Walkthrough

Walkthrough

EventMention 생성 계약이 문서의 정확한 SourceSpan, six-clock evidence, extractor version 및 review status를 요구하도록 변경되었습니다. span 정밀도·재현율 평가, cutoff 검증, 인스턴스 승격 거부 및 관련 문서와 테스트가 추가되었습니다.

Changes

Span-grounded EventMention

Layer / File(s) Summary
Mention 계약과 공개 API
crates/event_core/src/error.rs, crates/event_core/src/span_mention.rs, crates/event_core/src/lib.rs
MentionReviewStatus, MentionEvidenceClocks, span 정밀도·재현율 함수 및 5개 EventError 변형을 추가했습니다. 관련 타입과 함수를 공개 API로 export했습니다.
문서 span 기반 생성과 승격 제한
crates/event_core/src/mention.rs
EventMention::new이 문서와 SourceSpan을 검증하고 span에서 surface form을 생성합니다. document ID, clocks, extractor version 및 review status accessor를 제공합니다. span mention의 event instance 변환을 거부합니다.
Span 및 기존 계약 테스트
crates/event_core/tests/*
정확한 extent, cutoff eligibility, 중복·빈 입력·문서 불일치 오류 및 승격 거부를 검증합니다. 기존 링크·추적 테스트는 문서에 근거한 mention ID를 사용합니다.
계약 문서화
ARCHITECTURE.md, CHANGELOG.md, DOCUMENTATION.md, docs/...
span-grounded EventMention 계약, extent 평가, six-clock cutoff 및 현재 구현 범위를 관련 문서에 반영했습니다.

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

Merge Risk: 🔵 Low · up to dfaac

The new grounded-mention workflow is mergeable, but the tracking contract currently uses identical evidence for multiple mentions and therefore leaves a bounded gap in validating span and temporal ordering; owner awareness or follow-up is recommended.

Suggested reviewers: cursoragent

Sequence Diagram(s)

sequenceDiagram
  participant Caller
  participant DocumentRecord
  participant EventMention
  participant MentionEvidenceClocks
  Caller->>DocumentRecord: 문서 텍스트 제공
  Caller->>MentionEvidenceClocks: six-clock evidence 생성
  Caller->>EventMention: 문서, SourceSpan, clocks, version, status 전달
  EventMention->>DocumentRecord: span 문서 소속 및 surface form 검증
  EventMention->>MentionEvidenceClocks: available_time과 knowledge_cutoff 검증
  EventMention-->>Caller: 검증된 EventMention 반환
  Caller->>EventMention: event instance 변환 요청
  EventMention-->>Caller: SpanMentionIsNotEventInstance 오류 반환
Loading
🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 55.26% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 76 functions across 9 files. (11 skipped:… Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed 제목은 EventMention에 span grounding을 통합하는 PR의 주요 변경 사항을 정확하고 간결하게 설명합니다.
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.
Full details: Docstring Coverage

Explanation

Docstring coverage is 55.26% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 76 functions across 9 files. (11 skipped: 11 unsupported.)

✨ Finishing Touches 💡 1
📝 Generate docstrings 💡
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch cursor/span-grounded-mentions-a17b

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

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

@cursor cursor Bot changed the title Add span-grounded event mentions with exact-extent recovery (#170 / GAP-007) Fold span grounding into EventMention (#170 / GAP-007) Aug 25, 2026
@cursor
cursor Bot force-pushed the cursor/span-grounded-mentions-a17b branch from 4223fb1 to 0bbd116 Compare August 25, 2026 09:11
cursoragent and others added 3 commits August 25, 2026 10:04
Protected main already isolates TDT/CHRONOS scoring gates. Mentions still
lacked exact source extents. This slice binds each mention to one SourceSpan,
six-clock cutoff evidence, extractor version, and review status, and scores
ACE exact-extent precision/recall against known documentary truth.

Co-authored-by: Seongho Bae <seonghobae@users.noreply.github.com>
Close remaining fail-closed and half-rate paths on span-grounded mention
scoring so exact-extent recovery stays fully exercised.

Co-authored-by: Seongho Bae <seonghobae@users.noreply.github.com>
Issue #170 requires every mention to cite an exact source span. Remove the unused parallel mention type so EventMention can be constructed only from a document span, six-clock evidence, extractor version, and review status.

Co-authored-by: Seongho Bae <seonghobae@users.noreply.github.com>
@seonghobae
seonghobae marked this pull request as ready for review August 25, 2026 16:00
@chatgpt-codex-connector

Copy link
Copy Markdown

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

devin-ai-integration[bot]

This comment was marked as resolved.

coderabbitai[bot]

This comment was marked as resolved.

# Conflicts:
#	CHANGELOG.md
#	docs/product-technical-gap-baseline.md
The merge-resolution pass kept the stale 04:24Z snapshot; restore
main's c482cce-refreshed register (merged through #246) so the draft
does not regress the canonical operator-gap authority.
@seonghobae
seonghobae enabled auto-merge August 25, 2026 21:19

@devin-ai-integration devin-ai-integration Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Devin Review found 2 new potential issues.

Open in Devin Review

Comment on lines +80 to +83
) -> Result<Self, EventError> {
if available_time.instant().as_nanosecond() > knowledge_cutoff.instant().as_nanosecond() {
return Err(EventError::MentionIneligibleAtCutoff);
}

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📝 Info: Cutoff eligibility uses direct instant comparison

MentionEvidenceClocks::new gates eligibility with a direct as_nanosecond() comparison instead of temporal_core::evaluate_historical_eligibility. Equal instants are eligible, consistent with the doctoring note. The clocks are concrete single instants, so the simpler comparison is sufficient and honors the availability-before-cutoff contract.

Open in Devin Review

Was this helpful? React with 👍 or 👎 to provide feedback.

Comment on lines +53 to +54
let surface_form =
document.text()[source_span.byte_start()..source_span.byte_end()].to_string();

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📝 Info: Whitespace-only surface no longer rejected

The previous constructor rejected whitespace-only surface forms; the new one derives the surface from the exact span (crates/event_core/src/mention.rs:53-54), which can be whitespace. This follows the new exact-extent design, but the old non-whitespace invariant is gone.

Open in Devin Review

Was this helpful? React with 👍 or 👎 to provide feedback.

@opencode-agent
opencode-agent Bot disabled auto-merge August 25, 2026 22:02
@seonghobae
seonghobae enabled auto-merge August 25, 2026 23:40
@opencode-agent
opencode-agent Bot disabled auto-merge August 26, 2026 00:13
@seonghobae
seonghobae merged commit ba08ff5 into main Aug 26, 2026
32 checks passed
@seonghobae
seonghobae deleted the cursor/span-grounded-mentions-a17b branch August 26, 2026 00:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants