From e01a2bc521c90e2fe5940b39f679fbeac520af35 Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Tue, 8 Sep 2026 08:45:16 +0800 Subject: [PATCH 1/4] fix(search): preserve relevance ordering and bound evidence queries --- docs/search-audit.md | 137 ++++++++++++++ internal/app/search_explain.go | 3 + internal/app/search_test.go | 1 + internal/corpus/code.go | 10 +- internal/corpus/models.go | 1 + internal/corpus/repository_search.go | 8 +- internal/corpus/search.go | 172 ++++++------------ internal/corpus/search_benchmark_test.go | 109 +++++++++++ internal/corpus/search_modes.go | 2 +- internal/corpus/search_regression_test.go | 166 +++++++++++++++++ .../corpus/thread_search_evidence_test.go | 91 +++++++++ internal/corpus/thread_search_sql.go | 107 +++++++++++ 12 files changed, 678 insertions(+), 129 deletions(-) create mode 100644 docs/search-audit.md create mode 100644 internal/corpus/search_benchmark_test.go create mode 100644 internal/corpus/search_regression_test.go create mode 100644 internal/corpus/thread_search_evidence_test.go create mode 100644 internal/corpus/thread_search_sql.go diff --git a/docs/search-audit.md b/docs/search-audit.md new file mode 100644 index 00000000..dd74abe5 --- /dev/null +++ b/docs/search-audit.md @@ -0,0 +1,137 @@ +# Search audit: relevance and filter ownership + +Date: 2026-09-08. Baseline: `c1930cd`. + +This pass started with an ownership/residue scan of the repository and narrowed +into offline search. It traced query compilation, corpus SQL, ranking, cursors, +counts, and application match explanations. It used isolated SQLite corpora and +stored synthetic observations, without accessing a user's corpus or fetching +GitHub data. It is not a complete security or architecture audit. + +## Reproduced and fixed + +| Problem | Evidence on the baseline | Change | +| --- | --- | --- | +| Hydration dilutes strong title matches | Among 102 threads, `connection timeout` ranks a body-only configuration example above `connection timeout during startup` after the latter receives 2,000 unrelated discussion words. | Relevance places all-term title matches first, then retains weighted BM25 within each group. The title predicate uses FTS5, including for any-term searches. Updated sorting remains chronological. | +| Different label selections share a cursor key | A cursor for the single label `bug,urgent` is accepted for the two labels `bug` and `urgent`. Trimming also aliases ` bug` and `bug`. | Encode filter values structurally and preserve their values; sort the copied label list because label order does not change selection. Unicode case folding is also avoided because SQLite's built-in [`lower()`](https://www.sqlite.org/lang_corefunc.html#lower) does not provide general Unicode folding. | +| Unknown merge selection returns known unmerged PRs | The corpus accepts `ParseMergeFilter("unknown")`, but search returns the known unmerged PR and reports a total of one instead of the two unknown PRs. | One merge predicate now owns both row selection and exact counts. Unknown outcomes are selected explicitly, and are not reported as excluded unknowns when explicitly requested. | + +The three original regression tests failed against the baseline production +implementation before their fixes. Additional coverage checks any-term title +promotion, pagination between ranking groups, unchanged updated ordering, and +Unicode-distinct cursor filters. Existing tests cover title/label weights, +metadata filters, all/any term selection, literal operators and unmatched quotes, +facet replacement ordering, truncated evidence, and repository/code pagination. + +The `unknown` merge correction is at the corpus API. This change does not add an +unknown selector to the public thread-search tool's existing nullable boolean +input. + +## Ranking decision and cost + +SQLite's [FTS5 BM25 documentation](https://www.sqlite.org/fts5.html#the_bm25_function) +explains that document length affects rank. Column weights increase term +frequency contributions but do not isolate a short title from the length of its +hydrated discussion. A larger title weight alone would still leave that problem +at larger document sizes. + +The selected policy is intentionally explicit: a title matching every query +term precedes matches requiring other fields. This improves the reproduced +case, but can also promote a generic title above a more substantively relevant +body. It is a lexical retrieval rule, not evidence of semantic relevance. Scores +remain BM25 values, so callers should preserve result order instead of globally +re-sorting thread results by score. Match explanations and the architecture +contract describe the two groups. + +The additional indexed title lookup has a cost. Three 300 ms benchmark samples +on the same Linux/amd64 host, using the 102-thread regression fixture, gave: + +| Query | Baseline median | Changed median | +| --- | ---: | ---: | +| `connection timeout` (two matches) | 1.163 ms/op | 1.380 ms/op | +| `unrelated` (many matches, hydrated excerpt) | 27.388 ms/op | 27.402 ms/op | + +These short samples are diagnostic, not a scale benchmark or proof of latency +parity. The broad-query samples were noisy. Reproduce with: + +```sh +go test ./internal/corpus -run '^$' -bench BenchmarkThreadSearchRelevance -benchtime=300ms -count=3 +``` + +## Remaining opportunities + +1. Build a relevance dataset from actual failed searches and expected results. + The regression fixture establishes the hydration defect; it does not establish + that title-first ranking is best across real contribution-research tasks. + Compare ranking policies using judged queries before further tuning weights. +2. Evaluate word forms and code identifiers separately. The current indexes use + SQLite's default `unicode61` tokenizer. They do not configure stemming, + substring search, or camel-case splitting. SQLite documents distinct + [tokenizer options](https://www.sqlite.org/fts5.html#tokenizers); adopting one + changes matching semantics and needs an index/projection design and a recall + dataset, rather than an automatic fallback that silently broadens a query. +3. Continue profiling at larger sizes with realistic query selectivity. The + follow-up below bounds excerpt work, but the full-text match/ranking stage + still depends on corpus size. Small searches also incur extra planning cost. + +The earlier punctuation hypothesis was rejected: SQLite ignores empty quoted +phrases within these queries, and the existing literal-query regression passes. +The retired crawl-frontier response fields were also left in place because +[ADR 0006](adr/0006-retire-crawl-frontier.md) explicitly retains them. Similar +looking helpers were not merged merely because their source bodies matched. + +## Follow-up: bounded evidence work and shared owners + +The next pass implemented the excerpt-work and ranking-ownership opportunities. +Its baseline was the local tree containing the title, merge, and cursor fixes +above, not the earlier Git commit alone. + +Thread search now selects and materializes the filtered page of IDs before +building excerpts. Exact evidence lookup supplies a single ID to the same +attribution SQL. FTS row-ID constraints keep expensive excerpt generation away +from unrelated results. Page selection and count still share one read +transaction; this does not add writes, an index migration, or a network read. +The design uses SQLite's documented +[materialization boundary](https://www.sqlite.org/lang_with.html#materialization_hints) +to keep the page limit ahead of downstream evidence work. + +Three 200 ms samples per case on the same host gave these medians: + +| Workload | Before | After | +| --- | ---: | ---: | +| Selective query, 102-thread fixture | 1.295 ms | 2.192 ms | +| Broad query, 102-thread fixture | 26.751 ms | 3.064 ms | +| Scoped page, no background threads | 1.186 ms | 2.013 ms | +| Scoped page, 100 background threads | 9.574 ms | 2.244 ms | +| Scoped page, 1,000 background threads | 81.559 ms | 3.292 ms | +| Exact evidence, no background threads | 0.594 ms | 0.705 ms | +| Exact evidence, 100 background threads | 8.139 ms | 0.910 ms | +| Exact evidence, 1,000 background threads | 82.370 ms | 1.140 ms | + +The scope fixture holds one selected thread and varies only the number of +matching hydrated threads in another repository. These are synthetic local +benchmarks, not production latency guarantees. The small-query overhead is a +real tradeoff; the gain comes from bounding evidence work as other matches grow. + +```sh +go test ./internal/corpus -run '^$' -bench 'BenchmarkThreadSearch(HydratedScope|Relevance)' -benchtime=200ms -count=3 +``` + +The accompanying read-only regression traverses every page in both relevance +and updated order, compares ranks and evidence with exact lookups, verifies +counts and corpus revision, and checks cancellation. Page and exact reads share +the evidence implementation; preservation of global BM25 values also relies on +inspection of the unchanged ranking expression, not an independent rank oracle. +Existing facet tests retain +coverage of complete/stale replacement and truncation boundaries. + +Other duplicated owners were removed without changing their rules: + +- Repository and code search each define their BM25 SQL expression once, + including the expression used by cursor predicates and exact evidence reads. +- Radar candidate sorting and eligibility escalation use the same severity rule. +- `clustering.MemberRef.Equal` owns case-insensitive repository identity for + both neighbor self-exclusion and the corpus's canonical-member guard. + +This remains a focused improvement pass. Setup/release replacement helpers, +other domain state machines, and unrelated persistence paths were not refactored. diff --git a/internal/app/search_explain.go b/internal/app/search_explain.go index 971f350c..ca13638e 100644 --- a/internal/app/search_explain.go +++ b/internal/app/search_explain.go @@ -56,5 +56,8 @@ func explainMatchReasons(query string, match contracts.SearchMatch, freshness, n reasons = append(reasons, "no coverage recorded") } reasons = append(reasons, "score is weighted FTS5 BM25 rank converted from lower-is-better to higher-is-better relevance") + if match.Kind == "issue" || match.Kind == "pull_request" { + reasons = append(reasons, "thread relevance places all-term title matches first, then orders each group by score") + } return reasons } diff --git a/internal/app/search_test.go b/internal/app/search_test.go index d59a71bf..02231c62 100644 --- a/internal/app/search_test.go +++ b/internal/app/search_test.go @@ -368,6 +368,7 @@ func TestExplainMatchReturnsFactualReasons(t *testing.T) { want := []string{ "stored FTS5 index matched the query in thread", + "thread relevance places all-term title matches first", "source updated", "coverage includes metadata", } diff --git a/internal/corpus/code.go b/internal/corpus/code.go index 05af3e53..75eb7e87 100644 --- a/internal/corpus/code.go +++ b/internal/corpus/code.go @@ -490,9 +490,11 @@ func (c *Corpus) prepareCodeSearch(ctx context.Context, query string, opts CodeS return opts, ftsQuery, repo, cursor, err } +const codeSearchRankSQL = "bm25(code_documents_fts, 5.0, 1.0)" + func codeSearchStatement(ftsQuery string, opts CodeSearchOptions, cursor *searchCursor) (string, []any) { statement := ` - SELECT bm25(code_documents_fts, 5.0, 1.0), d.id, s.repo_owner, s.repo_name, s.commit_sha, d.path, + SELECT ` + codeSearchRankSQL + `, d.id, s.repo_owner, s.repo_name, s.commit_sha, d.path, snippet(code_documents_fts, -1, '', '', ' … ', 48), d.bytes, d.language, s.id, s.created_at FROM code_documents_fts JOIN code_documents d ON d.id = code_documents_fts.rowid @@ -507,10 +509,10 @@ func codeSearchStatement(ftsQuery string, opts CodeSearchOptions, cursor *search args = append(args, opts.Ref.Owner(), opts.Ref.Repo()) } if cursor != nil { - statement += ` AND (bm25(code_documents_fts, 5.0, 1.0) > ? OR (bm25(code_documents_fts, 5.0, 1.0) = ? AND d.id > ?))` + statement += ` AND (` + codeSearchRankSQL + ` > ? OR (` + codeSearchRankSQL + ` = ? AND d.id > ?))` args = append(args, cursor.Rank, cursor.Rank, cursor.ID) } - statement += ` ORDER BY bm25(code_documents_fts, 5.0, 1.0), d.id LIMIT ?` + statement += ` ORDER BY ` + codeSearchRankSQL + `, d.id LIMIT ?` return statement, append(args, opts.Page.Limit()+1) } @@ -659,7 +661,7 @@ func (c *Corpus) FindCodeSearchEvidence(ctx context.Context, docID int64, query } var evidence CodeSearchEvidence err := c.db.QueryRowContext(ctx, ` - SELECT bm25(code_documents_fts, 5.0, 1.0), + SELECT `+codeSearchRankSQL+`, snippet(code_documents_fts, -1, '', '', ' … ', 48) FROM code_documents_fts WHERE code_documents_fts MATCH ? AND rowid = ? diff --git a/internal/corpus/models.go b/internal/corpus/models.go index fb95877a..b7ee969e 100644 --- a/internal/corpus/models.go +++ b/internal/corpus/models.go @@ -71,6 +71,7 @@ type Thread struct { UpdatedAt time.Time // Rank and match fields are query-specific and populated only by search results. Rank float64 + MatchTitle bool MatchSource string MatchExcerpt string MatchUpdatedAt time.Time diff --git a/internal/corpus/repository_search.go b/internal/corpus/repository_search.go index bbd2c6b8..d3f1f431 100644 --- a/internal/corpus/repository_search.go +++ b/internal/corpus/repository_search.go @@ -8,6 +8,8 @@ import ( "strings" ) +const repositorySearchRankSQL = "bm25(repositories_fts, 10.0, 10.0, 5.0, 2.0)" + // RepositorySearchOptions scopes a paginated repository search. type RepositorySearchOptions struct { Page SearchPage @@ -94,7 +96,7 @@ func repositorySearchStatement(ftsQuery string, opts RepositorySearchOptions, cu if ftsQuery != "" { from = "FROM repositories_fts JOIN repositories ON repositories.id = repositories_fts.rowid" where = `WHERE repositories_fts MATCH ?` - rankSelect = "bm25(repositories_fts, 10.0, 10.0, 5.0, 2.0)" + rankSelect = repositorySearchRankSQL args = append(args, ftsQuery) } if cursor != nil { @@ -144,7 +146,7 @@ func scanRepositorySearchRows(rows *sql.Rows) ([]Repository, error) { func repositoryOrder(ftsQuery string, order SearchOrder) string { if ftsQuery != "" && !order.IsUpdated() { - return "bm25(repositories_fts, 10.0, 10.0, 5.0, 2.0), repositories.source_updated_at DESC, repositories.id" + return repositorySearchRankSQL + ", repositories.source_updated_at DESC, repositories.id" } return "repositories.source_updated_at DESC, repositories.id DESC" } @@ -164,7 +166,7 @@ func (c *Corpus) FindRepositorySearchEvidence(ctx context.Context, id int64, que } var evidence RepositorySearchEvidence err := c.db.QueryRowContext(ctx, ` - SELECT bm25(repositories_fts, 10.0, 10.0, 5.0, 2.0), + SELECT `+repositorySearchRankSQL+`, snippet(repositories_fts, -1, '', '', ' … ', 48) FROM repositories_fts WHERE repositories_fts MATCH ? AND rowid = ? diff --git a/internal/corpus/search.go b/internal/corpus/search.go index 85343f0c..a3016541 100644 --- a/internal/corpus/search.go +++ b/internal/corpus/search.go @@ -41,52 +41,9 @@ type ThreadSearchPage struct { UnknownMergeCount int } -const threadSearchMatchesSQL = ` - WITH facet_raw AS MATERIALIZED ( - SELECT fo.thread_id, fo.facet, - snippet(facet_observations_fts, 0, '', '', ' … ', 32) AS excerpt, - (SELECT MAX(snapshot.source_updated_at) - FROM facet_observations snapshot - WHERE snapshot.repository_id = fo.repository_id - AND snapshot.thread_id = fo.thread_id - AND snapshot.facet = fo.facet) AS source_updated_at, - bm25(facet_observations_fts) AS rank, fo.id - FROM facet_observations_fts - JOIN facet_observations fo ON fo.id = facet_observations_fts.rowid - WHERE facet_observations_fts MATCH ? AND fo.thread_id IS NOT NULL - ), facet_evidence AS ( - SELECT *, ROW_NUMBER() OVER (PARTITION BY thread_id ORDER BY rank, id) AS source_position - FROM facet_raw - ), bounded_facet_matches AS MATERIALIZED ( - SELECT d.thread_id, - snippet(threads_fts, 3, '', '', ' … ', 32) AS excerpt, - d.facets_updated_at AS source_updated_at - FROM threads_fts - JOIN thread_search_documents d ON d.thread_id = threads_fts.rowid - WHERE threads_fts MATCH ? - ), search_matches AS ( - SELECT d.thread_id, - bm25(threads_fts, 10.0, 5.0, 2.0, 0.5) AS rank, - COALESCE(fe.facet, CASE WHEN bf.thread_id IS NOT NULL THEN 'hydrated_facets' ELSE 'thread' END) AS source, - COALESCE(fe.excerpt, bf.excerpt, snippet(threads_fts, -1, '', '', ' … ', 32)) AS excerpt, - d.title || char(10) || d.labels || char(10) || d.body || char(10) || d.facets AS search_text, - COALESCE(fe.source_updated_at, bf.source_updated_at, t.source_updated_at) AS source_updated_at, - d.facets_truncated AS search_truncated - FROM threads_fts - JOIN thread_search_documents d ON d.thread_id = threads_fts.rowid - JOIN threads t ON t.id = d.thread_id - LEFT JOIN facet_evidence fe ON fe.thread_id = d.thread_id AND fe.source_position = 1 AND d.facets_truncated = 0 - LEFT JOIN bounded_facet_matches bf ON bf.thread_id = d.thread_id - WHERE threads_fts MATCH ? - )` - -func threadSearchArguments(ftsQuery string) []any { - return []any{ftsQuery, "facets : (" + ftsQuery + ")", ftsQuery} -} - // SearchThreads performs an FTS5 keyword search over thread title, body, and // searchable hydrated facet evidence. -// It returns matching threads ordered by FTS5 rank and limited to at most limit +// It prioritizes all-term title matches, then FTS5 rank, and returns at most limit // results. No network access occurs. func (c *Corpus) SearchThreads(ctx context.Context, query string, limit int) ([]Thread, error) { request, err := ParseSearchPage(limit, "") @@ -101,8 +58,8 @@ func (c *Corpus) SearchThreads(ctx context.Context, query string, limit int) ([] } // SearchThreadsPage performs an FTS5 keyword search with stable cursor -// pagination. Results are ordered by FTS5 rank ascending, then thread id -// ascending, so the same cursor always returns the same next page on an +// pagination. Relevance orders all-term title matches first, then FTS5 rank, +// newest source timestamp, and thread ID. A cursor returns the same next page on an // unchanged corpus. No network access occurs. func (c *Corpus) SearchThreadsPage(ctx context.Context, query string, filter SearchFilter) (ThreadSearchPage, error) { limit := filter.Page.Limit() @@ -123,38 +80,7 @@ func (c *Corpus) SearchThreadsPage(ctx context.Context, query string, filter Sea return ThreadSearchPage{}, err } - statement := threadSearchMatchesSQL + ` - SELECT m.rank, t.id, t.repository_id, t.kind, t.number, t.state, t.state_reason, t.title, t.body, t.author, t.author_association, t.labels, t.assignees, t.draft, t.locked, t.milestone, - t.source_created_at, t.source_updated_at, t.observation_sequence, t.created_at, t.updated_at, t.closed_at, t.merged_at, t.merged, t.merged_known, - m.source, m.excerpt, m.source_updated_at, m.search_truncated - FROM search_matches m - JOIN threads t ON t.id = m.thread_id - WHERE 1 = 1` - args := threadSearchArguments(ftsQuery) - if filter.Repository.IsScoped() { - statement += ` AND t.repository_id = ?` - args = append(args, filter.Repository.ID()) - } - if !filter.Kind.IsAny() { - statement += ` AND t.kind = ?` - args = append(args, filter.Kind.String()) - } - statement, args = appendThreadMetadataFilters(statement, args, filter) - if cursor != nil { - if filter.Order.IsUpdated() { - statement += ` AND (t.source_updated_at < ? OR (t.source_updated_at = ? AND t.id < ?))` - args = append(args, cursor.UpdatedAt, cursor.UpdatedAt, cursor.ID) - } else { - statement += ` AND (m.rank > ? OR (m.rank = ? AND (t.source_updated_at < ? OR (t.source_updated_at = ? AND t.id > ?))))` - args = append(args, cursor.Rank, cursor.Rank, cursor.UpdatedAt, cursor.UpdatedAt, cursor.ID) - } - } - if filter.Order.IsUpdated() { - statement += ` ORDER BY t.source_updated_at DESC, t.id DESC LIMIT ?` - } else { - statement += ` ORDER BY m.rank, t.source_updated_at DESC, t.id LIMIT ?` - } - args = append(args, limit+1) + statement, args := threadSearchPageStatement(ftsQuery, literalFTSQuery(query), filter, cursor) tx, err := c.db.BeginTx(ctx, &sql.TxOptions{ReadOnly: true}) if err != nil { @@ -182,14 +108,15 @@ func (c *Corpus) SearchThreadsPage(ctx context.Context, query string, filter Sea page.Threads = threads[:limit] last := page.Threads[len(page.Threads)-1] page.NextCursor = encodeCursor(searchCursor{ - Scope: "threads", - Query: query, - Repo: filter.Repository.String(), - Kind: filter.Kind.String(), - Filter: filterKey, - Rank: last.Rank, - UpdatedAt: encodeTime(last.SourceUpdatedAt), - ID: last.ID, + Scope: "threads", + Query: query, + Repo: filter.Repository.String(), + Kind: filter.Kind.String(), + Filter: filterKey, + Rank: last.Rank, + TitleMatch: last.MatchTitle, + UpdatedAt: encodeTime(last.SourceUpdatedAt), + ID: last.ID, }) } if filter.Merge.IsAny() && len(threads) <= limit && cursor == nil { @@ -220,15 +147,7 @@ func countThreadMatchSummary(ctx context.Context, tx *sql.Tx, ftsQuery string, f if filter.Merge.IsAny() { statement += `COUNT(*)` } else { - statement += `COALESCE(SUM(CASE - WHEN t.kind = 'pull_request' AND t.merged_known = 1 AND t.merged = ? THEN 1 - ELSE 0 - END), 0)` - if filter.Merge.IsMerged() { - args = append(args, 1) - } else { - args = append(args, 0) - } + statement += `COALESCE(SUM(CASE WHEN ` + threadMergePredicate(filter.Merge) + ` THEN 1 ELSE 0 END), 0)` } statement += `, COALESCE(SUM(CASE @@ -238,7 +157,7 @@ func countThreadMatchSummary(ctx context.Context, tx *sql.Tx, ftsQuery string, f FROM matching_threads m JOIN threads t ON t.id = m.thread_id WHERE 1 = 1` - if filter.Merge.IsAny() { + if filter.Merge.IsAny() || filter.Merge.IsUnknown() { args = append(args, 0) } else { args = append(args, 1) @@ -268,14 +187,16 @@ func (c *Corpus) FindThreadSearchEvidence(ctx context.Context, threadID int64, q if ftsQuery == "" { return ThreadSearchEvidence{}, false, nil } - statement := threadSearchMatchesSQL + ` + statement := `WITH page_threads AS MATERIALIZED ( + SELECT rowid AS thread_id, ` + threadSearchRankSQL + ` AS rank + FROM threads_fts WHERE threads_fts MATCH ? AND rowid = ? + )` + threadSearchEvidenceSQL + ` SELECT source, search_text, excerpt, source_updated_at, rank, search_truncated - FROM search_matches - WHERE thread_id = ?` + FROM search_matches` var evidence ThreadSearchEvidence var sourceUpdatedAt int64 var truncated int - args := append(threadSearchArguments(ftsQuery), threadID) + args := append([]any{ftsQuery, threadID}, threadSearchEvidenceArguments(ftsQuery)...) err := c.db.QueryRowContext(ctx, statement, args...).Scan( &evidence.Source, &evidence.Text, &evidence.Excerpt, &sourceUpdatedAt, &evidence.Rank, &truncated, ) @@ -314,12 +235,7 @@ func appendThreadMetadataFilters(query string, args []any, filter SearchFilter) args = append(args, filter.StateReason.String()) } if !filter.Merge.IsAny() { - merged := 0 - if filter.Merge.IsMerged() { - merged = 1 - } - query += ` AND t.merged = ? AND t.merged_known = 1` - args = append(args, merged) + query += ` AND ` + threadMergePredicate(filter.Merge) } if filter.Author != "" { query += ` AND lower(t.author) = lower(?)` @@ -350,16 +266,29 @@ func appendThreadMetadataFilters(query string, args []any, filter SearchFilter) return query, args } +// threadMergePredicate is shared by row selection and exact match counts. +func threadMergePredicate(merge MergeFilter) string { + switch { + case merge.IsUnknown(): + return "t.kind = 'pull_request' AND t.merged_known = 0" + case merge.IsMerged(): + return "t.kind = 'pull_request' AND t.merged_known = 1 AND t.merged = 1" + case merge.IsUnmerged(): + return "t.kind = 'pull_request' AND t.merged_known = 1 AND t.merged = 0" + default: + return "1 = 1" + } +} + func threadFilterKey(filter SearchFilter) string { labels := append([]string(nil), filter.Labels...) - for i := range labels { - labels[i] = strings.ToLower(strings.TrimSpace(labels[i])) - } slices.Sort(labels) - return strings.Join([]string{ - filter.State.String(), filter.StateReason.String(), filter.Merge.String(), strings.ToLower(filter.Author), strings.ToLower(filter.Association), strings.ToLower(filter.Assignee), strings.Join(labels, ","), + encodedLabels, _ := json.Marshal(labels) + key, _ := json.Marshal([]string{ + filter.State.String(), filter.StateReason.String(), filter.Merge.String(), filter.Author, filter.Association, filter.Assignee, string(encodedLabels), strconv.FormatInt(encodeTime(filter.UpdatedAfter), 10), strconv.FormatInt(encodeTime(filter.UpdatedBefore), 10), filter.Order.String(), filter.TermMatch.String(), - }, "|") + }) + return string(key) } // scanThreadsWithRank reads threads and the FTS5 rank value used for cursor @@ -373,7 +302,7 @@ func scanThreadsWithRank(rows *sql.Rows) ([]Thread, error) { var sourceCreated, src, created, updated, matchUpdated int64 var closed, mergedAt sql.NullInt64 var merged, mergedKnown, draft, locked, matchTruncated int - if err := rows.Scan(&rank, &t.ID, &t.RepositoryID, &t.Kind, &t.Number, &t.State, &stateReason, &t.Title, &body, &author, &authorAssociation, &labels, &assignees, &draft, &locked, &milestone, &sourceCreated, &src, &t.ObservationSequence, &created, &updated, &closed, &mergedAt, &merged, &mergedKnown, &t.MatchSource, &t.MatchExcerpt, &matchUpdated, &matchTruncated); err != nil { + if err := rows.Scan(&t.MatchTitle, &rank, &t.ID, &t.RepositoryID, &t.Kind, &t.Number, &t.State, &stateReason, &t.Title, &body, &author, &authorAssociation, &labels, &assignees, &draft, &locked, &milestone, &sourceCreated, &src, &t.ObservationSequence, &created, &updated, &closed, &mergedAt, &merged, &mergedKnown, &t.MatchSource, &t.MatchExcerpt, &matchUpdated, &matchTruncated); err != nil { return nil, err } if err := parseThreadProjection(&t); err != nil { @@ -433,14 +362,15 @@ func quoteFTSTerm(term string) string { // searchCursor is the product-owned opaque pagination cursor. It is encoded as // base64(JSON) and never interpreted by callers. type searchCursor struct { - Scope string `json:"s"` - Query string `json:"q"` - Repo string `json:"r,omitempty"` - Kind string `json:"k,omitempty"` - Filter string `json:"f,omitempty"` - Rank float64 `json:"rank,omitempty"` - UpdatedAt int64 `json:"u,omitempty"` - ID int64 `json:"id"` + Scope string `json:"s"` + Query string `json:"q"` + Repo string `json:"r,omitempty"` + Kind string `json:"k,omitempty"` + Filter string `json:"f,omitempty"` + Rank float64 `json:"rank,omitempty"` + TitleMatch bool `json:"title_match,omitempty"` + UpdatedAt int64 `json:"u,omitempty"` + ID int64 `json:"id"` } func encodeCursor(c searchCursor) string { diff --git a/internal/corpus/search_benchmark_test.go b/internal/corpus/search_benchmark_test.go new file mode 100644 index 00000000..21f40ceb --- /dev/null +++ b/internal/corpus/search_benchmark_test.go @@ -0,0 +1,109 @@ +package corpus + +import ( + "context" + "fmt" + "path/filepath" + "strings" + "testing" + "time" + + "github.com/morluto/gitcontribute/internal/domain" +) + +func BenchmarkThreadSearchRelevance(b *testing.B) { + ctx := context.Background() + c, err := Open(ctx, filepath.Join(b.TempDir(), "corpus.db")) + if err != nil { + b.Fatal(err) + } + b.Cleanup(func() { _ = c.Close() }) + seedSearchRelevance(b, c) + page, err := ParseSearchPage(10, "") + if err != nil { + b.Fatal(err) + } + for _, query := range []string{"connection timeout", "unrelated"} { + b.Run(query, func(b *testing.B) { + b.ReportAllocs() + for b.Loop() { + if _, err := c.SearchThreadsPage(ctx, query, SearchFilter{Page: page}); err != nil { + b.Fatal(err) + } + } + }) + } +} + +func BenchmarkThreadSearchHydratedScope(b *testing.B) { + for _, background := range []int{0, 100, 1000} { + b.Run(fmt.Sprintf("background_%d", background), func(b *testing.B) { + ctx := context.Background() + c, err := Open(ctx, filepath.Join(b.TempDir(), "corpus.db")) + if err != nil { + b.Fatal(err) + } + b.Cleanup(func() { _ = c.Close() }) + thread, scope := seedHydratedSearchScope(b, c, background) + page, err := ParseSearchPage(10, "") + if err != nil { + b.Fatal(err) + } + b.Run("repository_page", func(b *testing.B) { + b.ReportAllocs() + for b.Loop() { + result, err := c.SearchThreadsPage(ctx, "shared", SearchFilter{Repository: scope, Page: page}) + if err != nil || result.Total != 1 { + b.Fatalf("search total=%d, error=%v", result.Total, err) + } + } + }) + b.Run("exact_evidence", func(b *testing.B) { + b.ReportAllocs() + for b.Loop() { + _, found, err := c.FindThreadSearchEvidence(ctx, thread.ID, "shared") + if err != nil || !found { + b.Fatalf("found=%v, error=%v", found, err) + } + } + }) + }) + } +} + +func seedHydratedSearchScope(t testing.TB, c *Corpus, background int) (*Thread, ThreadRepositoryScope) { + t.Helper() + ctx := context.Background() + ref := domain.MustRepoRef("owner", "selected") + repo, err := c.ApplyRepositoryObservation(ctx, ref.Owner(), ref.Repo(), "selected", time.Unix(1, 0), `{}`) + if err != nil { + t.Fatal(err) + } + scope, err := NewThreadRepositoryScope(ref, repo.ID) + if err != nil { + t.Fatal(err) + } + other, err := c.ApplyRepositoryObservation(ctx, "owner", "background", "background", time.Unix(1, 0), `{}`) + if err != nil { + t.Fatal(err) + } + var selected *Thread + for i := 0; i <= background; i++ { + repoID := other.ID + if i == 0 { + repoID = repo.ID + } + thread, err := c.ApplyThreadObservation(ctx, repoID, domain.IssueKind, i+1, "open", "shared report", "body", "author", time.Unix(2, 0), `{}`) + if err != nil { + t.Fatal(err) + } + if i == 0 { + selected = thread + } + text := "shared " + strings.Repeat("discussion context ", 200) + if err := c.ApplyFacetObservationSet(ctx, repoID, &thread.ID, "issue_comments", time.Unix(3, 0), []FacetObservationInput{{Payload: `[]`, SearchText: text, SourceUpdatedAt: time.Unix(3, 0)}}, true, 0); err != nil { + t.Fatal(err) + } + } + return selected, scope +} diff --git a/internal/corpus/search_modes.go b/internal/corpus/search_modes.go index ee589c3d..661650a5 100644 --- a/internal/corpus/search_modes.go +++ b/internal/corpus/search_modes.go @@ -267,7 +267,7 @@ func (r ThreadStateReason) String() string { } } -// MergeFilter is the three-way merged, unmerged, or unrestricted predicate. +// MergeFilter selects merged, unmerged, unknown, or unrestricted outcomes. // Its zero value is unrestricted. type MergeFilter struct { value uint8 diff --git a/internal/corpus/search_regression_test.go b/internal/corpus/search_regression_test.go new file mode 100644 index 00000000..9a865d15 --- /dev/null +++ b/internal/corpus/search_regression_test.go @@ -0,0 +1,166 @@ +package corpus + +import ( + "context" + "slices" + "strings" + "testing" + "time" + + "github.com/morluto/gitcontribute/internal/domain" +) + +func TestThreadSearchCursorRejectsDifferentLabelSets(t *testing.T) { + t.Parallel() + ctx := context.Background() + c, _ := openTestCorpus(t) + repo, err := c.ApplyRepositoryObservation(ctx, "owner", "repo", "id", time.Unix(1, 0), `{}`) + if err != nil { + t.Fatal(err) + } + for number := 1; number <= 3; number++ { + _, err := c.UpsertThread(ctx, Thread{RepositoryID: repo.ID, Kind: domain.IssueKind, Number: number, State: "open", Title: "search term", Labels: []string{"bug,urgent", "bug", "urgent", " bug", "Ä", "ä"}, SourceUpdatedAt: time.Unix(int64(number), 0)}, `{}`) + if err != nil { + t.Fatal(err) + } + } + for _, test := range []struct{ labels, replacement []string }{ + {[]string{"bug,urgent"}, []string{"bug", "urgent"}}, + {[]string{" bug"}, []string{"bug"}}, + {[]string{"Ä"}, []string{"ä"}}, + } { + labels, replacement := test.labels, test.replacement + first, err := c.SearchThreadsPage(ctx, "term", SearchFilter{Labels: labels, Page: mustSearchPage(t, 1)}) + if err != nil || first.NextCursor == "" { + t.Fatalf("first page = %+v, %v", first, err) + } + if _, err := c.SearchThreadsPage(ctx, "term", SearchFilter{Labels: replacement, Page: mustSearchPage(t, 1, first.NextCursor)}); err == nil { + t.Errorf("cursor for labels %q accepted different labels %q", labels, replacement) + } + } +} + +func TestThreadSearchUnknownMergeFilter(t *testing.T) { + t.Parallel() + ctx := context.Background() + c, _ := openTestCorpus(t) + repo, err := c.ApplyRepositoryObservation(ctx, "owner", "repo", "id", time.Unix(1, 0), `{}`) + if err != nil { + t.Fatal(err) + } + for i, merge := range []domain.MergeStatus{domain.UnknownMergeStatus(), domain.UnknownMergeStatus(), domain.UnmergedStatus(), domain.MergedStatus(time.Time{})} { + _, err := c.UpsertThread(ctx, Thread{RepositoryID: repo.ID, Kind: domain.PullRequestKind, Number: i + 1, State: "closed", Title: "search term", Merge: merge, SourceUpdatedAt: time.Unix(int64(i+2), 0)}, `{}`) + if err != nil { + t.Fatal(err) + } + } + merge, err := ParseMergeFilter("unknown") + if err != nil { + t.Fatal(err) + } + first, err := c.SearchThreadsPage(ctx, "term", SearchFilter{Merge: merge, Page: mustSearchPage(t, 1)}) + if err != nil { + t.Fatal(err) + } + if first.Total != 2 || len(first.Threads) != 1 || first.Threads[0].Merge.Known() || first.NextCursor == "" || first.UnknownMergeCount != 0 { + t.Fatalf("unknown merge first page = %+v", first) + } + second, err := c.SearchThreadsPage(ctx, "term", SearchFilter{Merge: merge, Page: mustSearchPage(t, 1, first.NextCursor)}) + if err != nil { + t.Fatal(err) + } + if second.Total != 2 || len(second.Threads) != 1 || second.Threads[0].Merge.Known() || second.Threads[0].ID == first.Threads[0].ID || second.NextCursor != "" { + t.Fatalf("unknown merge second page = %+v", second) + } +} + +func TestThreadSearchKeepsTitleMatchesAheadOfIncidentalMentions(t *testing.T) { + t.Parallel() + ctx := context.Background() + c, _ := openTestCorpus(t) + seedSearchRelevance(t, c) + for _, mode := range []TermMatch{MatchAllTerms(), MatchAnyTerm()} { + first, err := c.SearchThreadsPage(ctx, "connection timeout", SearchFilter{TermMatch: mode, Page: mustSearchPage(t, 1)}) + if err != nil { + t.Fatal(err) + } + if first.Total != 2 || len(first.Threads) != 1 || first.Threads[0].Number != 1 || first.NextCursor == "" { + t.Fatalf("%s first page numbers = %v, total=%d", mode, searchThreadNumbers(first), first.Total) + } + second, err := c.SearchThreadsPage(ctx, "connection timeout", SearchFilter{TermMatch: mode, Page: mustSearchPage(t, 1, first.NextCursor)}) + if err != nil { + t.Fatal(err) + } + if second.Total != 2 || len(second.Threads) != 1 || second.Threads[0].Number != 2 || second.NextCursor != "" { + t.Fatalf("%s second page numbers = %v, total=%d", mode, searchThreadNumbers(second), second.Total) + } + } + updated, err := c.SearchThreadsPage(ctx, "connection timeout", SearchFilter{Order: UpdatedSearchOrder(), Page: mustSearchPage(t, 10)}) + if err != nil { + t.Fatal(err) + } + if got := searchThreadNumbers(updated); !slices.Equal(got, []int{2, 1}) { + t.Fatalf("updated order = %v", got) + } +} + +func searchThreadNumbers(page ThreadSearchPage) []int { + out := make([]int, len(page.Threads)) + for i, thread := range page.Threads { + out[i] = thread.Number + } + return out +} + +func seedSearchRelevance(t testing.TB, c *Corpus) { + t.Helper() + ctx := context.Background() + repo, err := c.ApplyRepositoryObservation(ctx, "owner", "repo", "id", time.Unix(1, 0), `{}`) + if err != nil { + t.Fatal(err) + } + for i := 1; i <= 102; i++ { + title, body := "unrelated report", "ordinary discussion" + if i == 1 { + title, body = "connection timeout during startup", "network request stalls" + } + if i == 2 { + title, body = "configuration example", "connection timeout" + } + thread, err := c.ApplyThreadObservation(ctx, repo.ID, domain.IssueKind, i, "open", title, body, "author", time.Unix(int64(i+1), 0), `{}`) + if err != nil { + t.Fatal(err) + } + if i == 1 { + if err := c.ApplyFacetObservationSet(ctx, repo.ID, &thread.ID, "issue_comments", time.Unix(200, 0), []FacetObservationInput{{SourceUpdatedAt: time.Unix(200, 0), Payload: `[]`, SearchText: strings.Repeat("unrelated discussion ", 1000)}}, true, 0); err != nil { + t.Fatal(err) + } + } + } +} + +func TestThreadSearchAnyTermPromotesOnlyCompleteTitleMatches(t *testing.T) { + t.Parallel() + ctx := context.Background() + c, _ := openTestCorpus(t) + repo, err := c.ApplyRepositoryObservation(ctx, "owner", "repo", "id", time.Unix(1, 0), `{}`) + if err != nil { + t.Fatal(err) + } + for i, title := range []string{"alpha", "beta", "alpha beta"} { + body := "" + if i == 2 { + body = strings.Repeat("discussion ", 1000) + } + if _, err := c.ApplyThreadObservation(ctx, repo.ID, domain.IssueKind, i+1, "open", title, body, "author", time.Unix(int64(i+2), 0), `{}`); err != nil { + t.Fatal(err) + } + } + page, err := c.SearchThreadsPage(ctx, "alpha beta", SearchFilter{TermMatch: MatchAnyTerm(), Page: mustSearchPage(t, 10)}) + if err != nil { + t.Fatal(err) + } + if page.Total != 3 || len(page.Threads) != 3 || page.Threads[0].Number != 3 { + t.Fatalf("any-term order = %v, total=%d", searchThreadNumbers(page), page.Total) + } +} diff --git a/internal/corpus/thread_search_evidence_test.go b/internal/corpus/thread_search_evidence_test.go new file mode 100644 index 00000000..13dd8913 --- /dev/null +++ b/internal/corpus/thread_search_evidence_test.go @@ -0,0 +1,91 @@ +package corpus + +import ( + "context" + "errors" + "testing" + "time" + + "github.com/morluto/gitcontribute/internal/domain" +) + +func TestThreadSearchPagesPreserveExactEvidenceInReadOnlyCorpus(t *testing.T) { + t.Parallel() + ctx := context.Background() + c, path := openTestCorpus(t) + selected, scope := seedHydratedSearchScope(t, c, 5) + for i := 1; i <= 12; i++ { + title, body, facet := "shared title", "body", "discussion" + switch i % 3 { + case 1: + title, body = "report", "shared body" + case 2: + title, facet = "report", "shared comment" + } + thread, err := c.ApplyThreadObservation(ctx, selected.RepositoryID, domain.IssueKind, i+1, "open", title, body, "author", time.Unix(int64(i+10), 0), `{}`) + if err != nil { + t.Fatal(err) + } + if err := c.ApplyFacetObservationSet(ctx, thread.RepositoryID, &thread.ID, "issue_comments", time.Unix(40, 0), []FacetObservationInput{{Payload: `[]`, SearchText: facet, SourceUpdatedAt: time.Unix(40, 0)}}, true, 0); err != nil { + t.Fatal(err) + } + } + reader, err := OpenReadOnly(ctx, path) + if err != nil { + t.Fatal(err) + } + t.Cleanup(func() { _ = reader.Close() }) + revision, err := reader.CorpusRevision(ctx) + if err != nil { + t.Fatal(err) + } + for _, order := range []SearchOrder{RelevanceSearchOrder(), UpdatedSearchOrder()} { + filter := SearchFilter{Repository: scope, Order: order, Page: mustSearchPage(t, 100)} + whole, err := reader.SearchThreadsPage(ctx, "shared", filter) + if err != nil || whole.Total != 13 || len(whole.Threads) != 13 { + t.Fatalf("whole total=%d, count=%d, err=%v", whole.Total, len(whole.Threads), err) + } + cursor, seen := "", 0 + for { + filter.Page = mustSearchPage(t, 3, cursor) + page, err := reader.SearchThreadsPage(ctx, "shared", filter) + if err != nil { + t.Fatal(err) + } + if page.Total != whole.Total || len(page.Threads) == 0 { + t.Fatalf("page total=%d, count=%d", page.Total, len(page.Threads)) + } + for _, thread := range page.Threads { + if seen >= len(whole.Threads) || thread.ID != whole.Threads[seen].ID || thread.Rank != whole.Threads[seen].Rank { + t.Fatalf("page differs at position %d: thread=%d rank=%g", seen, thread.ID, thread.Rank) + } + evidence, found, err := reader.FindThreadSearchEvidence(ctx, thread.ID, "shared") + if err != nil || !found { + t.Fatalf("exact evidence found=%v, error=%v", found, err) + } + if evidence.Rank != thread.Rank || evidence.Source != thread.MatchSource || evidence.Excerpt != thread.MatchExcerpt || !evidence.SourceUpdatedAt.Equal(thread.MatchUpdatedAt) || evidence.Truncated != thread.MatchTruncated { + t.Fatalf("page and exact evidence differ: thread=%+v evidence=%+v", thread, evidence) + } + seen++ + } + cursor = page.NextCursor + if cursor == "" { + break + } + } + if seen != 13 { + t.Fatalf("visited %d threads", seen) + } + } + if err := reader.RequireCorpusRevision(ctx, revision); err != nil { + t.Fatal(err) + } + cancelled, cancel := context.WithCancel(ctx) + cancel() + if _, err := reader.SearchThreadsPage(cancelled, "shared", SearchFilter{Repository: scope}); !errors.Is(err, context.Canceled) { + t.Fatalf("cancelled search: %v", err) + } + if _, _, err := reader.FindThreadSearchEvidence(cancelled, selected.ID, "shared"); !errors.Is(err, context.Canceled) { + t.Fatalf("cancelled evidence lookup: %v", err) + } +} diff --git a/internal/corpus/thread_search_sql.go b/internal/corpus/thread_search_sql.go new file mode 100644 index 00000000..865401fd --- /dev/null +++ b/internal/corpus/thread_search_sql.go @@ -0,0 +1,107 @@ +package corpus + +// Rank values remain global FTS5 BM25 values even when metadata filters narrow +// the candidate set. Page selection must precede hydrated excerpt generation. +const threadSearchRankSQL = "bm25(threads_fts, 10.0, 5.0, 2.0, 0.5)" + +// Both paginated and exact reads define page_threads, then use the same source +// attribution and truncation rules. Materialized evidence is limited to those IDs. +const threadSearchEvidenceSQL = `, facet_raw AS MATERIALIZED ( + SELECT fo.thread_id, fo.facet, + snippet(facet_observations_fts, 0, '', '', ' … ', 32) AS excerpt, + (SELECT MAX(snapshot.source_updated_at) + FROM facet_observations snapshot + WHERE snapshot.repository_id = fo.repository_id + AND snapshot.thread_id = fo.thread_id + AND snapshot.facet = fo.facet) AS source_updated_at, + bm25(facet_observations_fts) AS rank, fo.id + FROM facet_observations_fts + JOIN facet_observations fo ON fo.id = facet_observations_fts.rowid + WHERE facet_observations_fts MATCH ? + AND facet_observations_fts.rowid IN ( + SELECT id FROM facet_observations + WHERE thread_id IN (SELECT thread_id FROM page_threads) + ) + ), facet_evidence AS ( + SELECT *, ROW_NUMBER() OVER (PARTITION BY thread_id ORDER BY rank, id) AS source_position + FROM facet_raw + ), bounded_facet_matches AS MATERIALIZED ( + SELECT d.thread_id, + snippet(threads_fts, 3, '', '', ' … ', 32) AS excerpt, + d.facets_updated_at AS source_updated_at + FROM threads_fts + JOIN thread_search_documents d ON d.thread_id = threads_fts.rowid + WHERE threads_fts MATCH ? + AND threads_fts.rowid IN (SELECT thread_id FROM page_threads) + ), search_matches AS ( + SELECT d.thread_id, + p.rank, + COALESCE(fe.facet, CASE WHEN bf.thread_id IS NOT NULL THEN 'hydrated_facets' ELSE 'thread' END) AS source, + COALESCE(fe.excerpt, bf.excerpt, snippet(threads_fts, -1, '', '', ' … ', 32)) AS excerpt, + d.title || char(10) || d.labels || char(10) || d.body || char(10) || d.facets AS search_text, + COALESCE(fe.source_updated_at, bf.source_updated_at, t.source_updated_at) AS source_updated_at, + d.facets_truncated AS search_truncated + FROM threads_fts + JOIN thread_search_documents d ON d.thread_id = threads_fts.rowid + JOIN threads t ON t.id = d.thread_id + JOIN page_threads p ON p.thread_id = d.thread_id + LEFT JOIN facet_evidence fe ON fe.thread_id = d.thread_id AND fe.source_position = 1 AND d.facets_truncated = 0 + LEFT JOIN bounded_facet_matches bf ON bf.thread_id = d.thread_id + WHERE threads_fts MATCH ? + AND threads_fts.rowid IN (SELECT thread_id FROM page_threads) + )` + +func threadSearchEvidenceArguments(ftsQuery string) []any { + return []any{ftsQuery, "facets : (" + ftsQuery + ")", ftsQuery} +} + +func threadSearchPageStatement(ftsQuery, titleQuery string, filter SearchFilter, cursor *searchCursor) (string, []any) { + statement := `WITH title_matches AS MATERIALIZED ( + SELECT rowid AS thread_id FROM threads_fts WHERE threads_fts MATCH ? + ), ranked_threads AS ( + SELECT t.id AS thread_id, t.source_updated_at, + tm.thread_id IS NOT NULL AS title_match, ` + threadSearchRankSQL + ` AS rank + FROM threads_fts + JOIN threads t ON t.id = threads_fts.rowid + LEFT JOIN title_matches tm ON tm.thread_id = t.id + WHERE threads_fts MATCH ?` + args := []any{"title : (" + titleQuery + ")", ftsQuery} + if filter.Repository.IsScoped() { + statement += ` AND t.repository_id = ?` + args = append(args, filter.Repository.ID()) + } + if !filter.Kind.IsAny() { + statement += ` AND t.kind = ?` + args = append(args, filter.Kind.String()) + } + statement, args = appendThreadMetadataFilters(statement, args, filter) + statement += `), page_threads AS MATERIALIZED ( + SELECT * FROM ranked_threads m WHERE 1 = 1` + if cursor != nil { + if filter.Order.IsUpdated() { + statement += ` AND (m.source_updated_at < ? OR (m.source_updated_at = ? AND m.thread_id < ?))` + args = append(args, cursor.UpdatedAt, cursor.UpdatedAt, cursor.ID) + } else { + statement += ` AND (m.title_match < ? OR (m.title_match = ? AND (m.rank > ? OR (m.rank = ? AND (m.source_updated_at < ? OR (m.source_updated_at = ? AND m.thread_id > ?))))))` + args = append(args, cursor.TitleMatch, cursor.TitleMatch, cursor.Rank, cursor.Rank, cursor.UpdatedAt, cursor.UpdatedAt, cursor.ID) + } + } + order := threadSearchOrderSQL(filter.Order) + statement += ` ORDER BY ` + order + ` LIMIT ?)` + threadSearchEvidenceSQL + ` + SELECT m.title_match, m.rank, t.id, t.repository_id, t.kind, t.number, t.state, t.state_reason, t.title, t.body, t.author, t.author_association, t.labels, t.assignees, t.draft, t.locked, t.milestone, + t.source_created_at, t.source_updated_at, t.observation_sequence, t.created_at, t.updated_at, t.closed_at, t.merged_at, t.merged, t.merged_known, + e.source, e.excerpt, e.source_updated_at, e.search_truncated + FROM page_threads m + JOIN threads t ON t.id = m.thread_id + JOIN search_matches e ON e.thread_id = m.thread_id + ORDER BY ` + order + args = append(args, filter.Page.Limit()+1) + return statement, append(args, threadSearchEvidenceArguments(ftsQuery)...) +} + +func threadSearchOrderSQL(order SearchOrder) string { + if order.IsUpdated() { + return "m.source_updated_at DESC, m.thread_id DESC" + } + return "m.title_match DESC, m.rank, m.source_updated_at DESC, m.thread_id" +} From 52a63182695dde269e723ffe57fc0a080a6479b7 Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Tue, 8 Sep 2026 08:45:36 +0800 Subject: [PATCH 2/4] fix(evidence): unify reference ownership and preserve tracking failures --- docs/ownership-audit.md | 62 ++++++++++++++ internal/app/neighbors_test.go | 28 +++++++ internal/app/research_reader.go | 33 ++++---- internal/app/research_test.go | 43 ++++++++++ internal/clustering/models.go | 5 ++ internal/clustering/neighbors.go | 2 +- internal/clustering/references.go | 12 +-- internal/corpus/cluster_governance.go | 6 +- internal/corpus/tracking.go | 112 ++++++++++++++++++-------- internal/corpus/tracking_test.go | 98 ++++++++++++++++++++++ internal/radar/radar.go | 17 +--- 11 files changed, 338 insertions(+), 80 deletions(-) create mode 100644 docs/ownership-audit.md diff --git a/docs/ownership-audit.md b/docs/ownership-audit.md new file mode 100644 index 00000000..16a1a9aa --- /dev/null +++ b/docs/ownership-audit.md @@ -0,0 +1,62 @@ +# Ownership and failure-handling follow-up + +Date: 2026-09-08. This pass continues the [search audit](search-audit.md) +against the local tree containing its fixes. It examines stored research +relationships, PR collision references, triage link resolution, and nearby +search coverage reads. It is not an exhaustive repository audit. + +## Reproduced defects and changes + +| Boundary | Reproduction before the fix | Ownership or behavior change | +| --- | --- | --- | +| Inbound PR references in research briefs | Seven table cases fail: colon and URL closing references are downgraded; quoted, inline, and fenced examples become evidence; an explicit pull URL matches an issue; a quoted closing claim overrides a real mention. | Use `relatedwork.Extract`, which already owns outbound research relationship parsing. Respect explicit thread kinds and preserve the brief's existing mentions/claims-to-close vocabulary. | +| PR collision scoring | An inbound blockquote or outbound inline-code reference gives an otherwise unrelated PR a 0.45 collision score. | The cluster-member adapter uses the same unquoted-prose extractor. Existing positive collision tests retain their expected scores. | +| Failed triage writes | Cancellation during lookup or an insert-rejection trigger clears the caller's carried links despite returning an error. | Resolve a copy and publish its link fields only after the insert succeeds. | +| Unreadable triage targets | A repository with an invalid stored numeric value is treated as missing, and an unlinked event is persisted successfully. | Propagate projection lookup errors; distinguish missing rows from query failures in carried-link checks. Remove the redundant repository-parser wrapper. | + +These cases use isolated local SQLite corpora and public application/corpus +methods. The research fixture fails on unexpected GitHub access. Additional +tracking tests cover unreadable typed and untyped thread targets and successful +clearing of stale links. The three original tracking failure cases, seven +research cases, and both collision cases were observed failing before their +respective production fixes. + +GitHub documents closing keywords and optional colons in +[Linking a pull request to an issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue). +The shared local extractor also recognizes full GitHub thread URLs. These are +lexical claims from stored prose; they do not establish that GitHub will close an +issue, that a PR targets the default branch, or that a merge occurred. + +The research change removes per-PR regexp compilation but also performs the +shared extractor's Markdown filtering and relationship classification. No +latency improvement is claimed for this change without a benchmark. + +## Follow-up inspection and limits + +The follow-up traced both remaining cluster-reference consumers, the shared +relationship parser, the triage resolver's callers, and search coverage reads. +No additional demonstrated defect was selected in those boundaries after the +fixes above. Similar-looking URL adapters and reference equality checks were +not merged solely for matching source text: ambiguous references and exact +member identities have different contracts. + +Search still reads thread coverage once per returned match. Its existing batch +reader requires an explicit facet list; an empty list means no results, not all +facets. Replacing this with a hard-coded list would silently omit future facets. +A bounded all-facet API and representative end-to-end measurements are needed +before selecting that optimization. No performance benefit has been measured +for it in this pass. + +The earlier search audit records remaining relevance-dataset and scale-testing +opportunities. Exhausting possible improvements across a repository cannot be +proved by these passes; further changes should be selected from new behavioral +or profiling evidence. + +## Validation + +The independent review found no verified defects in the six changed production +and test files for this pass. It excluded the earlier search/radar changes and +the previously reviewed identity-helper removal. Focused behavioral tests and +the final `make verify` passed, including the uncached short suite, vet, full +lint, module tidiness, generated-output checks, and repository documentation +validation. diff --git a/internal/app/neighbors_test.go b/internal/app/neighbors_test.go index c12a2643..d6d9b5c2 100644 --- a/internal/app/neighbors_test.go +++ b/internal/app/neighbors_test.go @@ -467,3 +467,31 @@ func TestSimilarityCandidateWindowScalesWithRequestedLimit(t *testing.T) { t.Fatal("oversized similarity limit was accepted") } } + +func TestPullRequestCollisionsIgnoreQuotedReferences(t *testing.T) { + for _, direction := range []string{"inbound", "outbound"} { + t.Run(direction, func(t *testing.T) { + ctx := context.Background() + svc := newNeighborService(t) + t.Cleanup(func() { _ = svc.Close() }) + c, err := svc.openCorpus(ctx) + if err != nil { + t.Fatal(err) + } + repo := seedRepoForNeighbors(t, c) + queryBody, otherBody := "Implementation", "> depends on #1" + if direction == "outbound" { + queryBody, otherBody = "Example: `depends on #2`", "Implementation" + } + seedPullRequestForNeighbors(t, c, repo.ID, 1, "Parser", queryBody, "alice", "open", "main") + seedPullRequestForNeighbors(t, c, repo.ID, 2, "Theme", otherBody, "bob", "open", "dev") + result, err := svc.PullRequestCollisions(ctx, contracts.RepoRef{Owner: "owner", Repo: "repo"}, 1, 10) + if err != nil { + t.Fatal(err) + } + if len(result.Collisions) != 0 { + t.Fatalf("quoted example produced collisions: %+v", result.Collisions) + } + }) + } +} diff --git a/internal/app/research_reader.go b/internal/app/research_reader.go index 302fc803..05222027 100644 --- a/internal/app/research_reader.go +++ b/internal/app/research_reader.go @@ -4,9 +4,7 @@ import ( "context" "encoding/json" "fmt" - "regexp" "sort" - "strconv" "strings" "time" @@ -16,6 +14,7 @@ import ( "github.com/morluto/gitcontribute/internal/facets" "github.com/morluto/gitcontribute/internal/github" "github.com/morluto/gitcontribute/internal/health" + "github.com/morluto/gitcontribute/internal/relatedwork" "github.com/morluto/gitcontribute/internal/research" ) @@ -191,13 +190,12 @@ func appendOpenPRResearchRelations(ctx context.Context, c *corpus.Corpus, stored if pullRequest.Number == ref.Number && ref.Kind == domain.PullRequestKind { continue } - if !researchTextReferences(pullRequest.Title+"\n"+pullRequest.Body, ref) { + relation := researchPRRelation(pullRequest.Title+"\n"+pullRequest.Body, ref) + if relation == "" { continue } - relation := "mentions" basis := "open pull request explicitly references the target" - if researchPRCloses(pullRequest.Title+"\n"+pullRequest.Body, ref) { - relation = "claims_to_close" + if relation == "claims_to_close" { basis = "open pull request uses a closing keyword for the target" } source := research.SourceRef{ @@ -529,20 +527,19 @@ func researchReferenceURL(ref research.ThreadRef) string { return fmt.Sprintf("https://github.com/%s/%s/%d", ref.Repo, segment, ref.Number) } -func researchTextReferences(text string, target research.ThreadRef) bool { - for _, ref := range clustering.ExtractMemberRefs(text, target.Repo) { - if strings.EqualFold(ref.Owner, target.Repo.Owner()) && strings.EqualFold(ref.Repo, target.Repo.Repo()) && ref.Number == target.Number { - return true +func researchPRRelation(text string, target research.ThreadRef) string { + relation := "" + for _, ref := range relatedwork.Extract(text, target.Repo) { + if !strings.EqualFold(ref.Repo.String(), target.Repo.String()) || ref.Number != target.Number || + (ref.Kind != "" && ref.Kind != target.Kind) { + continue + } + if ref.Relation == relatedwork.RelationClaimsToClose { + return "claims_to_close" } + relation = "mentions" } - return false -} - -func researchPRCloses(text string, target research.ThreadRef) bool { - repo := regexp.QuoteMeta(target.Repo.String()) - number := regexp.QuoteMeta(strconv.Itoa(target.Number)) - pattern := regexp.MustCompile(`(?i)\b(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\s+(?:` + repo + `)?#` + number + `\b`) - return pattern.MatchString(text) + return relation } func normalizeResearchRelated(values []research.RelatedThread, limit int, capped *bool) []research.RelatedThread { diff --git a/internal/app/research_test.go b/internal/app/research_test.go index 5206fe15..999a1090 100644 --- a/internal/app/research_test.go +++ b/internal/app/research_test.go @@ -247,3 +247,46 @@ func assertResearchHealth(t *testing.T, section research.HealthSection) { t.Fatalf("health = %+v", section) } } + +func TestThreadResearchBriefInboundReferencesUseUnquotedProse(t *testing.T) { + for _, tc := range []struct { + name, body, relation string + }{ + {"bare", "Fixes #1", "claims_to_close"}, + {"colon", "Fixes: #1", "claims_to_close"}, + {"URL", "Fixes https://github.com/owner/repo/issues/1", "claims_to_close"}, + {"mention", "See #1", "mentions"}, + {"blockquote", "> Fixes #1", ""}, + {"inline code", "Example: `Fixes #1`", ""}, + {"fenced code", "```\nFixes #1\n```", ""}, + {"different repository", "Fixes other/repo#1", ""}, + {"different kind", "Fixes https://github.com/owner/repo/pull/1", ""}, + {"quoted closing with real mention", "> Fixes #1\n\nSee #1", "mentions"}, + } { + t.Run(tc.name, func(t *testing.T) { + fixture := newResearchFixture(t) + _, err := fixture.svc.corpus.UpsertThread(fixture.ctx, corpus.Thread{ + RepositoryID: fixture.repoID, Kind: domain.PullRequestKind, Number: 9, + State: "open", Title: "Implementation", Body: tc.body, SourceUpdatedAt: fixture.now, + }, `{}`) + if err != nil { + t.Fatal(err) + } + brief, err := fixture.svc.ThreadResearchBrief(fixture.ctx, research.ThreadRef{ + Repo: domain.MustRepoRef("owner", "repo"), Number: 1, + }) + if err != nil { + t.Fatal(err) + } + var got string + for _, pr := range brief.Sections.PullRequests.PullRequests { + if pr.Number == 9 { + got = pr.Relation + } + } + if got != tc.relation { + t.Fatalf("relation = %q, want %q", got, tc.relation) + } + }) + } +} diff --git a/internal/clustering/models.go b/internal/clustering/models.go index ca57c131..41b80616 100644 --- a/internal/clustering/models.go +++ b/internal/clustering/models.go @@ -16,6 +16,11 @@ type MemberRef struct { Number int } +// Equal compares thread identity, treating repository owner and name as case-insensitive. +func (m MemberRef) Equal(other MemberRef) bool { + return m.Number == other.Number && m.Kind == other.Kind && strings.EqualFold(m.Owner, other.Owner) && strings.EqualFold(m.Repo, other.Repo) +} + func (m MemberRef) String() string { return fmt.Sprintf("%s/%s:%s#%d", m.Owner, m.Repo, m.Kind, m.Number) } diff --git a/internal/clustering/neighbors.go b/internal/clustering/neighbors.go index 29bb216b..91579ddc 100644 --- a/internal/clustering/neighbors.go +++ b/internal/clustering/neighbors.go @@ -51,7 +51,7 @@ func Neighbors(ctx context.Context, query Candidate, candidates []Candidate, lim return nil, err } } - if sameMemberRef(c.Ref(), query.Ref()) { + if c.Ref().Equal(query.Ref()) { continue } score := rule.Compare(preparedQuery, rule.Prepare(duplicateThread(c))) diff --git a/internal/clustering/references.go b/internal/clustering/references.go index bbcc3831..d6ab9102 100644 --- a/internal/clustering/references.go +++ b/internal/clustering/references.go @@ -1,22 +1,16 @@ package clustering import ( - "strings" - "github.com/morluto/gitcontribute/internal/domain" - "github.com/morluto/gitcontribute/internal/similarity" + "github.com/morluto/gitcontribute/internal/relatedwork" ) -// ExtractMemberRefs adapts exact GitHub references to cluster member values. +// ExtractMemberRefs adapts unquoted GitHub references to cluster member values. func ExtractMemberRefs(text string, defaultRepo domain.RepoRef) []MemberRef { - refs := similarity.ExtractRefs(text, defaultRepo) + refs := relatedwork.Extract(text, defaultRepo) out := make([]MemberRef, len(refs)) for i, ref := range refs { out[i] = MemberRef{Owner: ref.Repo.Owner(), Repo: ref.Repo.Repo(), Kind: ref.Kind, Number: ref.Number} } return out } - -func sameMemberRef(a, b MemberRef) bool { - return a.Number == b.Number && a.Kind == b.Kind && strings.EqualFold(a.Owner, b.Owner) && strings.EqualFold(a.Repo, b.Repo) -} diff --git a/internal/corpus/cluster_governance.go b/internal/corpus/cluster_governance.go index bbc109ca..424ed9e5 100644 --- a/internal/corpus/cluster_governance.go +++ b/internal/corpus/cluster_governance.go @@ -60,7 +60,7 @@ func (c *Corpus) AddClusterOverride(ctx context.Context, clusterID int64, ref cl if err != nil { return fmt.Errorf("decode cluster repository: %w", err) } - if action == clustering.OverrideExclude && sameClusterMemberRef(ref, canonical) { + if action == clustering.OverrideExclude && ref.Equal(canonical) { return errors.New("cannot exclude the canonical member") } if _, err := tx.ExecContext(ctx, `INSERT INTO cluster_overrides @@ -96,7 +96,3 @@ func validateClusterMemberRef(ref clustering.MemberRef) error { } return nil } - -func sameClusterMemberRef(a, b clustering.MemberRef) bool { - return a.Number == b.Number && a.Kind == b.Kind && strings.EqualFold(a.Owner, b.Owner) && strings.EqualFold(a.Repo, b.Repo) -} diff --git a/internal/corpus/tracking.go b/internal/corpus/tracking.go index 563061e5..37360325 100644 --- a/internal/corpus/tracking.go +++ b/internal/corpus/tracking.go @@ -31,10 +31,15 @@ var _ tracking.Repository = (*Corpus)(nil) // RecordTriageEvent stores a triage event with optional foreign-key-safe links. func (c *Corpus) RecordTriageEvent(ctx context.Context, e *tracking.TriageEvent) error { - if err := resolveTriageLinks(ctx, c, e); err != nil { + resolved := *e + if err := resolveTriageLinks(ctx, c, &resolved); err != nil { return err } - return c.recordTriageEventTx(ctx, c.db, e) + if err := c.recordTriageEventTx(ctx, c.db, &resolved); err != nil { + return err + } + *e = resolved + return nil } func (c *Corpus) recordTriageEventTx(ctx context.Context, db dbExecer, e *tracking.TriageEvent) error { @@ -124,23 +129,51 @@ func (c *Corpus) importTriageEventTx(ctx context.Context, tx *sql.Tx, e *trackin func resolveTriageLinks(ctx context.Context, c *Corpus, e *tracking.TriageEvent) error { // Verify any carried foreign keys still exist in this corpus and clear stale // ones so imports remain safe across corpora. - if e.RepositoryID != nil && !c.repoExists(ctx, *e.RepositoryID) { - e.RepositoryID = nil + if e.RepositoryID != nil { + exists, err := c.repoExists(ctx, *e.RepositoryID) + if err != nil { + return fmt.Errorf("verify triage repository link: %w", err) + } + if !exists { + e.RepositoryID = nil + } } - if e.ThreadID != nil && !c.threadExists(ctx, *e.ThreadID) { - e.ThreadID = nil + if e.ThreadID != nil { + exists, err := c.threadExists(ctx, *e.ThreadID) + if err != nil { + return fmt.Errorf("verify triage thread link: %w", err) + } + if !exists { + e.ThreadID = nil + } } - if e.InvestigationID != "" && !c.investigationExists(ctx, e.InvestigationID) { - e.InvestigationID = "" + if e.InvestigationID != "" { + exists, err := c.investigationExists(ctx, e.InvestigationID) + if err != nil { + return fmt.Errorf("verify triage investigation link: %w", err) + } + if !exists { + e.InvestigationID = "" + } } - if e.OpportunityID != "" && !c.opportunityExists(ctx, e.OpportunityID) { - e.OpportunityID = "" + if e.OpportunityID != "" { + exists, err := c.opportunityExists(ctx, e.OpportunityID) + if err != nil { + return fmt.Errorf("verify triage opportunity link: %w", err) + } + if !exists { + e.OpportunityID = "" + } } if e.RepositoryID == nil && e.TargetKind == tracking.TargetRepository { - ref, err := parseRepoRef(e.TargetRef) + ref, err := domain.ParseRepoRef(e.TargetRef) if err == nil { - if repo, err := c.GetRepository(ctx, ref.Owner(), ref.Repo()); err == nil && repo != nil { + repo, err := c.GetRepository(ctx, ref.Owner(), ref.Repo()) + if err != nil { + return fmt.Errorf("resolve repository link: %w", err) + } + if repo != nil { e.RepositoryID = &repo.ID } } @@ -162,7 +195,11 @@ func resolveTriageLinks(ctx context.Context, c *Corpus, e *tracking.TriageEvent) if e.ThreadID == nil && (e.TargetKind == tracking.TargetIssue || e.TargetKind == tracking.TargetPullRequest || e.TargetKind == tracking.TargetThread) { repoRef, number, ok := parseThreadRef(e.TargetRef) if ok { - if repo, err := c.GetRepository(ctx, repoRef.Owner(), repoRef.Repo()); err == nil && repo != nil { + repo, err := c.GetRepository(ctx, repoRef.Owner(), repoRef.Repo()) + if err != nil { + return fmt.Errorf("resolve thread repository link: %w", err) + } + if repo != nil { e.RepositoryID = &repo.ID var kind domain.ThreadKind switch e.TargetKind { @@ -171,14 +208,17 @@ func resolveTriageLinks(ctx context.Context, c *Corpus, e *tracking.TriageEvent) case tracking.TargetPullRequest: kind = domain.PullRequestKind } + var thread *Thread if kind != "" { - if thread, err := c.GetThread(ctx, repo.ID, kind, number); err == nil && thread != nil { - e.ThreadID = &thread.ID - } + thread, err = c.GetThread(ctx, repo.ID, kind, number) } else { - if thread, err := c.GetThreadByNumber(ctx, repo.ID, number); err == nil && thread != nil { - e.ThreadID = &thread.ID - } + thread, err = c.GetThreadByNumber(ctx, repo.ID, number) + } + if err != nil { + return fmt.Errorf("resolve thread link: %w", err) + } + if thread != nil { + e.ThreadID = &thread.ID } } } @@ -186,16 +226,12 @@ func resolveTriageLinks(ctx context.Context, c *Corpus, e *tracking.TriageEvent) return nil } -func parseRepoRef(ref string) (domain.RepoRef, error) { - return domain.ParseRepoRef(ref) -} - func parseThreadRef(ref string) (domain.RepoRef, int, bool) { repoRef, numText, ok := strings.Cut(ref, "#") if !ok { return domain.RepoRef{}, 0, false } - repo, err := parseRepoRef(repoRef) + repo, err := domain.ParseRepoRef(repoRef) if err != nil { return domain.RepoRef{}, 0, false } @@ -206,28 +242,40 @@ func parseThreadRef(ref string) (domain.RepoRef, int, bool) { return repo, number, true } -func (c *Corpus) repoExists(ctx context.Context, id int64) bool { +func (c *Corpus) repoExists(ctx context.Context, id int64) (bool, error) { var one int err := c.db.QueryRowContext(ctx, `SELECT 1 FROM repositories WHERE id=?`, id).Scan(&one) - return err == nil + if errors.Is(err, sql.ErrNoRows) { + return false, nil + } + return err == nil, err } -func (c *Corpus) threadExists(ctx context.Context, id int64) bool { +func (c *Corpus) threadExists(ctx context.Context, id int64) (bool, error) { var one int err := c.db.QueryRowContext(ctx, `SELECT 1 FROM threads WHERE id=?`, id).Scan(&one) - return err == nil + if errors.Is(err, sql.ErrNoRows) { + return false, nil + } + return err == nil, err } -func (c *Corpus) investigationExists(ctx context.Context, id string) bool { +func (c *Corpus) investigationExists(ctx context.Context, id string) (bool, error) { var one int err := c.db.QueryRowContext(ctx, `SELECT 1 FROM investigations WHERE id=?`, id).Scan(&one) - return err == nil + if errors.Is(err, sql.ErrNoRows) { + return false, nil + } + return err == nil, err } -func (c *Corpus) opportunityExists(ctx context.Context, id string) bool { +func (c *Corpus) opportunityExists(ctx context.Context, id string) (bool, error) { var one int err := c.db.QueryRowContext(ctx, `SELECT 1 FROM opportunities WHERE id=?`, id).Scan(&one) - return err == nil + if errors.Is(err, sql.ErrNoRows) { + return false, nil + } + return err == nil, err } func nullInt64(v *int64) sql.NullInt64 { diff --git a/internal/corpus/tracking_test.go b/internal/corpus/tracking_test.go index 19eac520..e9b61238 100644 --- a/internal/corpus/tracking_test.go +++ b/internal/corpus/tracking_test.go @@ -586,3 +586,101 @@ func containsAny(s string, subs []string) bool { func contains(s, sub string) bool { return len(sub) > 0 && strings.Contains(s, sub) } + +func TestRecordTriageEventPreservesInputOnFailure(t *testing.T) { + for _, failure := range []string{"canceled lookup", "rejected insert"} { + t.Run(failure, func(t *testing.T) { + c, _ := openTestCorpus(t) + ctx := context.Background() + if failure == "canceled lookup" { + var cancel context.CancelFunc + ctx, cancel = context.WithCancel(ctx) + cancel() + } else if _, err := c.db.ExecContext(ctx, `CREATE TRIGGER reject_triage BEFORE INSERT ON triage_events BEGIN SELECT RAISE(ABORT, 'rejected'); END`); err != nil { + t.Fatal(err) + } + missingID := int64(99999) + event := tracking.TriageEvent{ID: "failed", TargetKind: tracking.TargetRepository, TargetRef: "owner/repo", Outcome: tracking.OutcomeViewed, + RepositoryID: &missingID, ThreadID: &missingID, InvestigationID: "missing", OpportunityID: "missing"} + before := event + if err := c.RecordTriageEvent(ctx, &event); err == nil { + t.Fatal("expected failure") + } + if event != before { + t.Fatalf("failed record changed caller input: before %+v, after %+v", before, event) + } + }) + } +} + +func TestRecordTriageEventRejectsUnreadableTarget(t *testing.T) { + ctx := context.Background() + c, _ := openTestCorpus(t) + repo, err := c.ApplyRepositoryObservation(ctx, "owner", "repo", "123", time.Unix(1, 0).UTC(), `{}`) + if err != nil { + t.Fatal(err) + } + // SQLite's dynamic typing permits malformed imported numeric values; a + // projection decoding failure must not be interpreted as a missing target. + if _, err := c.db.ExecContext(ctx, `UPDATE repositories SET stars='invalid' WHERE id=?`, repo.ID); err != nil { + t.Fatal(err) + } + event := tracking.TriageEvent{ID: "unreadable", TargetKind: tracking.TargetRepository, TargetRef: "owner/repo", Outcome: tracking.OutcomeViewed} + if err := c.RecordTriageEvent(ctx, &event); err == nil { + t.Fatal("unreadable repository was treated as missing") + } + events, err := c.ListTriageEvents(ctx, tracking.TriageEventFilter{}) + if err != nil { + t.Fatal(err) + } + if len(events) != 0 { + t.Fatalf("persisted events after failed resolution: %+v", events) + } +} + +func TestRecordTriageEventClearsMissingLinksAfterSuccessfulWrite(t *testing.T) { + c, _ := openTestCorpus(t) + missingID := int64(99999) + event := tracking.TriageEvent{ID: "missing", TargetKind: tracking.TargetRepository, TargetRef: "owner/repo", Outcome: tracking.OutcomeViewed, + RepositoryID: &missingID, ThreadID: &missingID, InvestigationID: "missing", OpportunityID: "missing"} + if err := c.RecordTriageEvent(context.Background(), &event); err != nil { + t.Fatal(err) + } + if event.RepositoryID != nil || event.ThreadID != nil || event.InvestigationID != "" || event.OpportunityID != "" { + t.Fatalf("stale links remain: %+v", event) + } +} + +func TestRecordTriageEventRejectsUnreadableThread(t *testing.T) { + for _, kind := range []tracking.TargetKind{tracking.TargetIssue, tracking.TargetThread} { + t.Run(string(kind), func(t *testing.T) { + ctx := context.Background() + c, _ := openTestCorpus(t) + repo, err := c.ApplyRepositoryObservation(ctx, "owner", "repo", "123", time.Unix(1, 0).UTC(), `{}`) + if err != nil { + t.Fatal(err) + } + thread, err := c.ApplyThreadObservation(ctx, repo.ID, domain.IssueKind, 1, "open", "bug", "body", "alice", time.Unix(2, 0).UTC(), `{}`) + if err != nil { + t.Fatal(err) + } + if _, err := c.db.ExecContext(ctx, `UPDATE threads SET source_updated_at='invalid' WHERE id=?`, thread.ID); err != nil { + t.Fatal(err) + } + event := tracking.TriageEvent{ID: "unreadable", TargetKind: kind, TargetRef: "owner/repo#1", Outcome: tracking.OutcomeViewed} + if err := c.RecordTriageEvent(ctx, &event); err == nil { + t.Fatal("unreadable thread was treated as missing") + } + if event.RepositoryID != nil { + t.Fatal("failed resolution changed repository link") + } + events, err := c.ListTriageEvents(ctx, tracking.TriageEventFilter{}) + if err != nil { + t.Fatal(err) + } + if len(events) != 0 { + t.Fatalf("persisted events after failed resolution: %+v", events) + } + }) + } +} diff --git a/internal/radar/radar.go b/internal/radar/radar.go index 6bfd36ed..8b2cacdc 100644 --- a/internal/radar/radar.go +++ b/internal/radar/radar.go @@ -298,8 +298,8 @@ func Rank(repo RepositorySnapshot, issues []IssueSnapshot, opts Options) (*Repor sort.SliceStable(report.Candidates, func(i, j int) bool { left, right := report.Candidates[i], report.Candidates[j] - if eligibilityOrder(left.Eligibility) != eligibilityOrder(right.Eligibility) { - return eligibilityOrder(left.Eligibility) < eligibilityOrder(right.Eligibility) + if eligibilitySeverity(left.Eligibility) != eligibilitySeverity(right.Eligibility) { + return eligibilitySeverity(left.Eligibility) < eligibilitySeverity(right.Eligibility) } if left.Score != right.Score { return left.Score > right.Score @@ -763,16 +763,3 @@ func confidence(metadataComplete, threadsComplete, commentsComplete, guidanceAva return "low" } } - -func eligibilityOrder(value Eligibility) int { - switch value { - case EligibilityReadyToCode: - return 0 - case EligibilityNeedsDiagnosis: - return 1 - case EligibilityNeedsCoordination: - return 2 - default: - return 3 - } -} From a6a8f909e9797a519d5ec180856acded891c462e Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Tue, 8 Sep 2026 08:49:02 +0800 Subject: [PATCH 3/4] fix(mcp): preserve evidence completeness and durable job ownership --- CONTRIBUTING.md | 4 +- docs/architecture.md | 29 ++- docs/audits/2026-09-08/coverage.md | 79 +++++++ docs/concurrency-ranking-audit.md | 106 ++++++++++ docs/external-tool-audit.md | 169 +++++++++++++++ docs/mcp.md | 13 +- internal/app/concurrency_ranking_test.go | 208 +++++++++++++++++++ internal/app/duplicates_test.go | 2 +- internal/app/job_executor.go | 11 +- internal/app/mcp_external_audit_test.go | 137 ++++++++++++ internal/app/mcp_github_acquisition.go | 1 + internal/app/mcp_github_acquisition_test.go | 4 + internal/app/mcp_job_artifacts.go | 7 +- internal/app/mcp_recovery_test.go | 41 ++++ internal/app/mcp_related_work.go | 29 ++- internal/app/mcp_validation_resources.go | 39 ++++ internal/app/neighbors_related_work.go | 61 ++++-- internal/contracts/workflow_service.go | 2 + internal/corpus/jobs.go | 36 ++-- internal/corpus/jobs_test.go | 23 ++ internal/mcpcontract/operation_contracts.go | 28 +-- internal/mcpcontract/scalable_contracts.go | 13 ++ internal/mcpcontract/validation_resources.go | 29 +++ internal/mcpserver/resource_templates.go | 6 + internal/mcpserver/resources.go | 17 ++ 25 files changed, 1022 insertions(+), 72 deletions(-) create mode 100644 docs/audits/2026-09-08/coverage.md create mode 100644 docs/concurrency-ranking-audit.md create mode 100644 docs/external-tool-audit.md create mode 100644 internal/app/concurrency_ranking_test.go create mode 100644 internal/app/mcp_external_audit_test.go create mode 100644 internal/app/mcp_validation_resources.go create mode 100644 internal/mcpcontract/validation_resources.go diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 03602e30..92738cc5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -51,10 +51,10 @@ make check make verify ``` -`make verify` runs uncached tests, changed-code linting, module-tidiness checks, +`make verify` runs uncached tests, full-repository linting, module-tidiness checks, generated-output verification, and documentation validation. It is the complete local check, while CI adds platform, coverage, security, and focused race jobs. -`make lint-full` is available for auditing existing repository-wide lint debt. +`make lint-full` runs the full lint check on its own. Use `make test-uncached` when only a fresh test run is needed. Use focused race tests for changes involving SQLite transactions, goroutines, diff --git a/docs/architecture.md b/docs/architecture.md index 49b7b36f..5647c4d0 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -288,8 +288,10 @@ The agent may inspect the stored request and explicitly resubmit an idempotent operation after reviewing the failure. Each `JobExecutor` registers an opaque owner ID and periodically updates its -lease. A new executor reconciles only running jobs whose owner is absent or -stale. It must never fail jobs owned by another live process. +lease. Queued work is persisted with its owner atomically at admission. A new +executor reconciles queued and running jobs whose owner is absent or stale; it +must never fail jobs owned by another live process. Reconciled terminal state +also stops the original worker, and losing the owner stops further admission. ```text queued -> running -> succeeded @@ -297,6 +299,7 @@ queued -> running -> succeeded -> cancelled ``` +Queued work can also fail on restart or be cancelled before it starts. Terminal states do not transition again. Cancellation is first persisted, then delivered to an in-process worker directly or observed by one executor-wide poll that checks all active job IDs together. Executors cap both running and @@ -552,9 +555,20 @@ authority; duplicated query columns are checked against that manifest while decoding and discarded rather than exposed as a second source of truth. Title, labels, body, and hydrated evidence are materialized into one search -document per thread and ranked by one BM25 invocation. The facet index only +document per thread. Relevance puts threads whose titles match every query +term first, including in `match_mode=any`; one BM25 invocation orders matches +within each group. This prevents unrelated hydrated discussion from pushing a +full title match below an incidental body or facet mention through document +length normalization. The title group uses the same FTS tokenizer and literal +query terms as retrieval, without a second string matcher. The facet index only identifies the matching evidence source and excerpt. A thread page and its exact -count share one read transaction. Counts use a lean FTS match set rather than +count share one read transaction. Search selects ranked, filtered thread IDs +and the page boundary before generating hydrated excerpts. A materialized page +limits excerpt work to the requested page plus its next-page sentinel. Exact +evidence lookup uses the same attribution SQL over one selected thread, without +constructing evidence for other matching threads. Each search index defines its +BM25 weights once for selection, ordering, pagination, and explanations. +Counts use a lean FTS match set rather than recomputing ranking and excerpts, and the first-page no-overflow case derives its total directly from the returned rows. @@ -571,7 +585,9 @@ partial search document. Transport pages are collapsed into one semantic facet document, and matches report the source facet plus a bounded excerpt. Untrusted discussion remains searchable data and cannot grant capabilities. Cursors encode their query and scope so they cannot be reused for a different search. -Ordering always has a deterministic tie-breaker. +Thread cursors include the title group and encode filter values structurally, +so punctuation within a label cannot alias a different label set. Ordering +always has a deterministic tie-breaker. Hydrated search text is materialized once per complete facet replacement and bounded to 262,144 characters per thread. Results expose `match_truncated=true` when that bound omitted text; complete API coverage must @@ -579,7 +595,8 @@ not be mistaken for complete search-text coverage. FTS rank is retrieval evidence and must not be relabeled as a separately hand-written score. Match explanations report the actual lower-is-better BM25 -rank and the indexed document or hydrated facet that supplied the excerpt; +rank (within the title group for thread relevance) and the indexed document +or hydrated facet that supplied the excerpt; they do not guess token matches with a second string matcher. Freshness and coverage are separate facts. Lens ranking uses a bounded population and therefore does not support cursor pagination. diff --git a/docs/audits/2026-09-08/coverage.md b/docs/audits/2026-09-08/coverage.md new file mode 100644 index 00000000..dd671b07 --- /dev/null +++ b/docs/audits/2026-09-08/coverage.md @@ -0,0 +1,79 @@ +# External MCP invocation coverage — 2026-09-08 + +Every advertised tool was invoked. `returned` means a non-error response, not necessarily complete evidence. `queued` requires the terminal job outcomes in the audit report. Error counts include rejected test inputs and environmental failures. Raw logs and temporary runtime artifacts were removed after the follow-up validation at the user's request. Counts below preserve the original audit summary. + +| Tool | Baseline calls | Candidate calls | Observed envelope/status | +| --- | ---: | ---: | --- | +| `code.index_repositories` | 1 | 0 | queued | +| `corpus.analyze_fix_patterns` | 1 | 0 | partial | +| `corpus.ensure_coverage` | 1 | 0 | queued | +| `corpus.explain_match` | 1 | 0 | returned | +| `corpus.find_clusters` | 1 | 0 | complete | +| `corpus.find_competing_pull_requests` | 1 | 1 | partial | +| `corpus.find_duplicates` | 1 | 1 | partial | +| `corpus.find_neighbors` | 1 | 0 | complete | +| `corpus.find_precedents` | 1 | 0 | complete | +| `corpus.find_pull_request_overlaps` | 1 | 0 | complete | +| `corpus.get_actor_facets` | 1 | 0 | returned | +| `corpus.get_actors` | 1 | 0 | returned | +| `corpus.get_coverage` | 1 | 0 | partial | +| `corpus.get_repositories` | 1 | 0 | returned | +| `corpus.get_thread_facets` | 1 | 0 | returned | +| `corpus.get_threads` | 2 | 0 | returned, tool_error | +| `corpus.list_concerns` | 1 | 0 | returned | +| `corpus.materialize_repository_dossier` | 1 | 0 | returned | +| `corpus.rank_contribution_candidates` | 1 | 0 | complete | +| `corpus.search_actors` | 1 | 0 | returned | +| `corpus.search_code` | 1 | 0 | partial | +| `corpus.search_contributions` | 1 | 0 | returned | +| `corpus.search_pull_request_feedback` | 1 | 0 | partial | +| `corpus.search_pull_requests` | 1 | 0 | partial | +| `corpus.search_repositories` | 1 | 0 | returned | +| `corpus.search_threads` | 1 | 3 | returned, tool_error | +| `evidence.import_manifest` | 1 | 0 | returned | +| `github.compare_fork` | 2 | 0 | current, tool_error | +| `github.get_authenticated_identity` | 1 | 0 | tool_error | +| `github.index_pull_request_feedback` | 1 | 0 | queued | +| `github.read_source_files` | 2 | 1 | complete, tool_error | +| `github.search_repositories` | 2 | 0 | complete, tool_error | +| `github.search_threads` | 1 | 0 | partial | +| `github.search_users` | 1 | 0 | returned | +| `github.sync_pull_request_ci` | 2 | 0 | queued, tool_error | +| `github.sync_pull_request_feedback` | 1 | 0 | queued | +| `github.sync_pull_request_portfolio` | 1 | 0 | queued | +| `github.sync_repository_context` | 1 | 0 | queued | +| `github.sync_thread_facets` | 1 | 0 | queued | +| `github.sync_threads` | 1 | 0 | queued | +| `github.sync_user_contributions` | 1 | 0 | queued | +| `github.sync_user_organizations` | 1 | 0 | queued | +| `github.sync_user_pinned_items` | 1 | 0 | queued | +| `github.sync_user_repositories` | 1 | 0 | queued | +| `github.sync_user_social_accounts` | 1 | 0 | queued | +| `github.sync_users` | 1 | 0 | queued | +| `github.wait_pull_request_checks` | 1 | 0 | queued | +| `jobs.cancel` | 1 | 0 | returned | +| `jobs.get` | 6 | 1 | protocol_error, returned | +| `research.query_deepwiki` | 1 | 0 | complete | +| `validation.attach_junit_report` | 1 | 0 | returned | +| `validation.attach_receipt` | 1 | 0 | returned | +| `validation.define` | 1 | 0 | returned | +| `validation.run` | 1 | 0 | queued | +| `workflow.create_concern` | 1 | 0 | returned | +| `workflow.export_manifest` | 2 | 0 | returned, tool_error | +| `workflow.get_catalog_contract` | 1 | 1 | returned | +| `workflow.get_source_audit_contract` | 1 | 0 | returned | +| `workflow.link_concern` | 1 | 0 | returned | +| `workflow.link_pull_request` | 1 | 0 | returned | +| `workflow.prepare_contribution` | 1 | 0 | returned | +| `workflow.promote_concern` | 1 | 0 | returned | +| `workflow.promote_opportunity` | 1 | 0 | returned | +| `workflow.record_hypothesis` | 1 | 0 | returned | +| `workflow.set_concern_status` | 1 | 0 | returned | +| `workflow.start_investigation` | 1 | 0 | returned | +| `workflow.update_concern` | 1 | 0 | returned | +| `workflow.verify_published_draft` | 1 | 0 | unknown | +| `workspace.adopt` | 2 | 0 | returned, tool_error | +| `workspace.check_merge_conflicts` | 1 | 0 | returned | +| `workspace.create` | 1 | 0 | queued | +| `workspace.inspect_commit_changes` | 1 | 0 | returned | +| `workspace.plan_semantic_commits` | 1 | 0 | returned | diff --git a/docs/concurrency-ranking-audit.md b/docs/concurrency-ranking-audit.md new file mode 100644 index 00000000..73e83d94 --- /dev/null +++ b/docs/concurrency-ranking-audit.md @@ -0,0 +1,106 @@ +# Concurrency and ranking follow-up — 2026-09-08 + +## Need for jobs and SDK support + +GitContribute already uses the latest stable official Go MCP SDK, **v1.7.0** +(released July 28). The newest prerelease checked was **v1.8.0-pre.2** (September 4). +Both the Go module registry and GitHub release metadata were checked, and both +versions' source was inspected. Neither supplies a task runtime or `TaskStore` +that can replace the application executor. Context7 had no matching task API +documentation, so this conclusion rests on the tagged source and official +release documentation, not on a missing search result alone. +[Stable release](https://github.com/modelcontextprotocol/go-sdk/releases/tag/v1.7.0), +[prerelease](https://github.com/modelcontextprotocol/go-sdk/releases/tag/v1.8.0-pre.2). + +The current Tasks extension standardizes durable handles, polling, results, and +cooperative cancellation. Servers still own durable creation and execution; +clients must opt into the extension. Protocol support would replace an adapter +surface, not SQLite persistence, admission limits, or process ownership. +Retain the executor for acquisition, indexing, and validation; ordinary bounded +reads stay synchronous. No second task implementation or prerelease upgrade was +added. The prerelease's cancellation and teardown fixes merit a separate upgrade +evaluation when adopting it. +[Tasks extension](https://modelcontextprotocol.io/extensions/tasks/overview). + +## Reproduced defects and corrections + +| Case | Observed before correction | Corrected behavior | +| --- | --- | --- | +| Abandoned queue | A single-slot executor had one running job and a queued job. After another corpus connection aged and reconciled its owner, the queued job remained queued forever. | Persist owner and queued row together. Reconcile queued and running jobs for missing/stale owners, while preserving live-owner work. | +| Reconciled worker | Reconciliation marked running work failed, but its callback remained active because the cancellation poll only checked cancellation timestamps and missing rows. | Terminal durable state also stops work. Missing-owner heartbeats stop the executor and further admission; terminal results cannot be overwritten. | +| Unrelated ranked evidence | An exact match, weak positive match, and disjoint title produced three findings. Competing-PR matches were automatically contradicting evidence. | Remove exact zero-score findings while preserving weak positive candidates and their order. Similarity produces inconclusive evidence, including competing PR candidates. | +| Hidden candidate cap | Among 201 threads, an older exact match fell outside the first 200 candidates. The resulting empty findings claimed complete status. | Propagate candidate truncation independently from finding count. Increasing the limit recovered the exact match; at the hard maximum, recovery does not suggest a smaller/repeated limit. | + +The first three cases failed on the starting production code; the candidate-cap +case failed after zero-score filtering and before bound propagation. Focused +regressions passed after correction. Additional tests cover refusal to replace +a queued job's owner, loss of owner stopping admission, and preservation of live +owners. Existing job, cancellation, and ownership regressions were also run. + +The ranking fixture is a small deterministic relevance check, not a broad +retrieval benchmark: exact and partial title overlap are retained in order, +disjoint tokens are excluded, and an older excluded match is recovered by an +explicit larger bound. Generic nearest-neighbor ranking and duplicate-v1 weights +are unchanged. The recent-first candidate cap can still miss older matches; +that limitation is now visible. An exact-sized bound conservatively reports +truncation even if there is no additional result. + +## External validation + +Separate standalone MCP server processes shared only the task-owned corpus. +A bounded `python3 -c "import time; time.sleep(8)"` validation command made job +states observable without running repository-controlled code. A 12-second +command timeout bounded each process. Six submissions exercised the default +four running slots plus two waiting admissions. + +- A second process cancelled one running and one queued job; both reached the + cancelled terminal outcome. +- Closing the submitting server's stdin cancelled and joined the remaining + work; all six jobs were terminal and cancelled. +- A fresh submitting server was killed with four running and two queued jobs. + After the ten-second owner lease expired, a new executor reconciled all six + to failed. Work was not automatically replayed. Abrupt termination does not + prove synchronous termination of child processes; these commands were bounded. +- The preserved Cobra investigation was queried again. Its tiny positive scores + still produced candidates, with unknown source coverage and inconclusive + evidence relations. Rounded `0.00` displays did not establish exact zero. + +The probe initially used the wrong job response keys; it was corrected to read +`execution_state` and terminal `outcome` before the successful lifecycle run. +Those harness errors were not product defects. All task-owned runtime artifacts +and raw logs were removed after validation as requested; regression source and +this summary remain. + +## Research and remaining limits + +SQLite WAL supports concurrent readers but still serializes writes. Existing +reconciliation uses `BEGIN IMMEDIATE`, so no heartbeat can interleave between +liveness inspection and the corresponding updates. These fixes use that same +transaction rather than introducing another lock/lease owner. +[SQLite isolation](https://www.sqlite.org/isolation.html). + +The Go race detector checks only executed paths; deterministic lifecycle tests +and a real multi-process workload complement it. Cross-process logical races +are not established or excluded by a clean race-detector run alone. +[Go race detector](https://go.dev/doc/articles/race_detector). + +A broad ranking claim requires representative queries and independently judged +relevance, with precision and recall measured over the same collection. This +follow-up does not tune weights or claim a global precision/recall improvement +from a three-document fixture. Larger judged workloads, prolonged writer stalls, +lease-expiry under heavy load, and Windows process termination remain useful +follow-ups. +[IR evaluation](https://nlp.stanford.edu/IR-book/html/htmledition/information-retrieval-system-evaluation-1.html). + +## Final validation + +`make verify` passed after incorporating the current base's SQLite 1.56.0 +update. The focused race command below also passed on that base: + +```sh +go test -race -short -p=1 -parallel=4 -count=1 -timeout 120s ./internal/app ./internal/corpus -run 'Test.*Job|Test.*Owner|Test.*Reconcil|TestRelatedWork|TestDuplicateAndCollision' +``` + +The external workload preceded the dependency update. Final tests cover the +updated dependency, but the external multi-process probe was not repeated after +its task-owned runtime was removed. The Go MCP SDK version did not change. diff --git a/docs/external-tool-audit.md b/docs/external-tool-audit.md new file mode 100644 index 00000000..e0b4ee87 --- /dev/null +++ b/docs/external-tool-audit.md @@ -0,0 +1,169 @@ +# External tool audit — 2026-09-08 + +The standalone GitContribute MCP server received calls to all **73 advertised +tools** in an isolated, persistent audit workspace. Four confirmed defects were +fixed: invalid detailed index-job responses, incorrect source completeness, +false complete coverage in related-work checks, and missing validation-group +handoffs. Invocation coverage is not complete behavioral coverage or evidence +that no defects remain. + +The [tool-by-tool coverage table](audits/2026-09-08/coverage.md) records 85 baseline +and eight candidate tool calls from the initial pass. That pass recorded 108 +JSON-RPC exchanges. Temporary runtime artifacts and raw logs were removed after +the follow-up at the user's request; this report retains the findings and coverage +summary. See the [concurrency and ranking follow-up](concurrency-ranking-audit.md). + +## Runtime and evidence identity + +- Source base: `c1930cd3f5f8ee37ef993935ef716f22f24b1684`, with existing search and + ownership changes already present. This is not a clean-HEAD comparison. +- Standalone runtime: version `dev`, Go 1.26.5, Linux amd64, Git 2.53.0; + MCP protocol `2025-11-25`, stdio JSON-RPC, initialized before tool calls. +- Baseline catalog: 73 tools, fingerprint + `747848aa0864e7bb3d188b2ae7975541cb40fdd057e4e9035521e5d4cb981dd5`. +- Candidate catalog: 73 tools, fingerprint + `7f36215dd9a57942d7549589f218e79222ac77591a2ec08ee627f048164a355f`. +- The separately connected installed runtime reported version `1.0.0`, 62 tools, + fingerprint `b8ae9dfde5bd81a139ab0095e5353320fa955c3739311c62c94b2cfaed8281ed`. + Only its catalog contract was queried; source identity equivalence was not assumed. +- Candidate `--read-only` catalog advertised 33 tools. This filters read-only + annotations and still permits explicit external reads; it is not offline mode. + +Baseline and candidate labels identify separate executable sessions against the +same evolving audit corpus, not a controlled latency comparison. The starting +tracked diff did not capture pre-existing untracked files. Documentation does +not preserve a replayable runtime snapshot after artifact cleanup. + +## Real workload + +Public GitHub REST reads searched `spf13/cobra` for completion-related closed +pull requests, inspected PR #2467, acquired repository/thread/actor facets, +read commit-bound source, indexed code, and inspected feedback and CI coverage. +The main ref resolved to `adbc8813901bba65827259daa8e22ff94ec1f30e`; +PR #2467's head was `4a56f4211a97e7796c3f81022231d0c776510453`. +Live search returned three of 205 results with a next page and partial status. +Code acquisition indexed 65 text files out of 66 tracked entries, skipping one +nontext file without truncation. DeepWiki retrieval was explicitly external +and retained derived-external provenance. + +Local reads exercised thread/code/actor/contribution/feedback search, facets, +coverage, ranking, clusters, neighbors, precedents, overlaps, and explanations. +Local workflows created an investigation, hypothesis, opportunity, concern, +draft, workspace, and adopted checkout; inspected Git changes, merge conflicts, +and semantic commit plans; and linked evidence and a pull request. Draft +preparation was not publication. No GitHub mutation occurred. + +Validation executed only `git diff --check` in the task-owned checkout. Both +individual runs passed, but their group remained **inconclusive** because no +observation contract established a functional result. A separately recorded +external execution was attached as a digest-bound receipt with a JUnit summary; +a manifest import preserved its limited external provenance. These observations +do not prove a Cobra bug fixed. No repository-controlled code ran during crawl +or indexing. + +Selected CLI smoke checks also succeeded: `metadata --json`, `status --json`, +`doctor --json`, and `search threads completion --repo spf13/cobra --limit 2 --json`. +This is not full CLI, installation, upgrade, or cross-platform coverage. + +## Confirmed defects and fixes + +| Defect | Reproduction and impact | Correction and validation | +| --- | --- | --- | +| Detailed index jobs fail output validation | A successful index job embedded a partially populated full artifact, including null provenance where the output schema required an object. One such item broke an entire detailed job batch. | Job summaries now own a narrow artifact reference; the exact resource owns the full manifest. A failing MCP-boundary regression became green. The candidate retrieved the same index job together with a validation job, then read the returned index resource successfully. | +| Source response loses completeness | Two successfully acquired files had accurate artifact metadata but zero requested/completed counts and an empty completeness status in the compact response. | Copy the persisted artifact's completeness into the response. Regression failed before the fix and passed after it. The same external request returned two requested/two complete/zero failed, and its exact source resource was readable. | +| Related-work coverage overclaims | Duplicate and competing-PR checks reported `coverage: complete` despite incomplete stored thread coverage. | Consult the repository's thread coverage; missing/incomplete coverage yields unknown coverage, partial status, and typed sync recovery. MCP regressions cover missing, incomplete, and complete cases. Both real checks now preserve unknown coverage. | +| Validation job has no usable group handoff | A completed validation job exposed a group ID without a resource or attempt identities, leaving the agent unable to follow that result directly. | Add a narrow validation-group resource and exact returned URI/follow-up. A failing boundary regression became green. External resource read exposed both attempt IDs and the inconclusive group classification without commands, environment, or host paths. | + +Documentation also now describes `--read-only` accurately and states that +`make verify` runs full repository lint. Existing search/ownership work is +covered separately in [search audit](search-audit.md) and +[ownership audit](ownership-audit.md); it was excluded from this pass's independent +diff review. + +## Coverage limits and correct negative behavior + +Acquisition jobs were polled through `jobs.get`, rather than treating queued +acknowledgments as completion. Repository context, threads, exact thread facets, +profiles, social accounts, repository listings, exact PR feedback, coverage, +indexing, workspace creation, validation execution, and checks waiting reached +successful terminal execution. A successful job can still contain bounded or +incomplete facet coverage. + +Organization, pinned-item, and contribution facets remained partial. Repository +list coverage was truncated. Repository-wide feedback discovery stopped at its +page cap; CI acquisition exhausted its three-request budget. PR portfolio +acquisition encountered a GraphQL deadline. These limitations were retained as +partial/unknown evidence. Authenticated identity returned an authentication +error; no authenticated success path was exercised. + +Other deliberately or accidentally invalid inputs were rejected: incorrect +search/source/CI argument shapes, comparing a fork to itself, a manifest's +inconsistent head identity, and adopting an already-bound workspace path. The +calls were corrected where applicable; these input errors are not product bugs. +A stale durable snapshot returned `snapshot_expired`. In the initial pass cancellation was tested +only against a terminal job. The follow-up exercised cross-process running and +queued cancellation, graceful shutdown, and abrupt restart recovery. Published-draft verification returned unknown against an +unsynced target; a matching published draft was not tested. + +Candidate search pages returned different thread identities, and reusing the +cursor with another query returned `invalid search cursor`. This confirms the +sampled pagination boundary, not relevance quality across repositories. Local +search retained unknown population coverage. No cold/warm benchmark, concurrency +stress test, controlled model evaluation, authenticated large-corpus workload, +or exhaustive resource-template matrix was performed. + +## Remaining improvement opportunities + +1. **Related-work signal quality (addressed in follow-up):** some candidates display `score 0.00: no + strong signal`, yet competing-PR evidence uses a contradicting relation. + Rounded display values do not prove the exact numeric score is zero. Build + a judged query set and inspect score/relation calibration before changing + thresholds. The follow-up removes exact zero-score findings, changes similarity evidence + to inconclusive, and preserves candidate bounds. Wider relevance calibration + remains unmeasured. +2. **Acquisition recovery:** repeat the partial actor/portfolio workload with + authenticated access and bounded retries to separate permission, rate-limit, + and timeout causes. Avoid increasing budgets without measuring useful yield. +3. **Result size and polling cost:** logs record response sizes indirectly and + per-call timings. Measure large detailed job batches and facet payloads before + changing response defaults; keep manifests in resources and summaries narrow. + This audit establishes a correctness improvement, not a measured speedup. +4. **Evidence navigation:** evaluate whether manifest imports should expose + evidence identities directly; current summaries may require another lookup. +5. **Lifecycle and trust boundaries:** the follow-up adds external running-cancel, + graceful shutdown, and interrupted-process reconciliation workloads. Malformed + resources, prolonged writer stalls, and larger contention workloads remain + useful future cases. +6. **Deployment identity:** the connected 62-tool runtime differs from the + tested 73-tool source build. Verify catalog fingerprints when deploying; + this audit did not update the installed runtime. + +## Research and validation + +The protocol requires structured tool results to conform to their advertised +output schema. That makes the detailed job failure a contract defect even +though indexing itself succeeded. The artifact-reference fix keeps summary +fields truthful while providing the full resource separately. +[MCP tools specification](https://modelcontextprotocol.io/specification/2025-11-25/server/tools). +The probe follows the protocol initialization sequence. +[MCP lifecycle](https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle). + +GitHub recommends authenticated access, bounded/queued requests, and respecting +retry/reset headers. Apply these to follow-up acquisition experiments; do not +interpret anonymous failures as absence of repository or actor data. +[GitHub REST best practices](https://docs.github.com/en/rest/using-the-rest-api/best-practices-for-using-the-rest-api), +[rate limits](https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api), +[troubleshooting](https://docs.github.com/en/rest/using-the-rest-api/troubleshooting-the-rest-api). +MCP documentation was consulted through Context7; GitHub guidance came from +official documentation. + +Focused regressions reproduced the four defects before fixes and passed after. +An independent review of this pass's exact production/test/documentation diff +reported no verified findings and passed application, MCP server, and contract +tests plus whitespace checks. It did not independently repeat the external +stdio workload. Final `make verify` passed formatting, vet, and every uncached short-test +package, then stopped on one test import-grouping lint finding. After that +formatting-only correction, `make fmt-check lint-full tidy-check generate-check +docs-check` passed with zero lint issues and current generated outputs. Thus +all verification gates passed; unchanged behavioral tests were not repeated. +`git diff --check` also passed. diff --git a/docs/mcp.md b/docs/mcp.md index 402d344d..7b1a3883 100644 --- a/docs/mcp.md +++ b/docs/mcp.md @@ -28,8 +28,10 @@ external read; its prose is untrusted derived context and never overrides GitHub facts. No MCP tool mutates GitHub or executes repository-controlled code during acquisition, indexing, or research. -Use `--read-only` when starting the MCP server to omit network, local-write, -Git, and process capabilities. `workflow.get_catalog_contract` reports the +Use `--read-only` when starting the MCP server to expose only tools annotated +as read-only. This omits acquisition, local writes, and validation execution, +but retains pure external reads and non-mutating Git inspection. It is not an +offline mode; inspect each tool's documented authority and open-world annotation. `workflow.get_catalog_contract` reports the running version, catalog mode, tool count, deterministic fingerprint, and availability of key routes. Restart the MCP connection after setup, upgrade, or registration changes before comparing that contract with `tools/list`. @@ -176,6 +178,13 @@ competing work” conclusion. Base/candidate validation remains an explicit process composition: +After `validation.run`, poll `jobs.get` and follow its exact +`gitcontribute://validation-group/{id}` resource URI. The resource exposes +persisted group outcomes and attempt run IDs for `validation.attach_junit_report`; +a succeeded job alone does not establish that its test attempts passed. +Code-index jobs likewise return a compact digest-bound reference; read its exact +resource URI for file counts, manifest coverage, and provenance. + 1. Use `workspace.adopt` or `workspace.create` for authorized worktrees. 2. Call `validation.define` with the exact command and workspace identities. 3. Call `validation.run` with the requested target and repetitions. diff --git a/internal/app/concurrency_ranking_test.go b/internal/app/concurrency_ranking_test.go new file mode 100644 index 00000000..b65bb024 --- /dev/null +++ b/internal/app/concurrency_ranking_test.go @@ -0,0 +1,208 @@ +package app + +import ( + "context" + "fmt" + "strings" + "testing" + "time" + + "github.com/morluto/gitcontribute/internal/contracts" + "github.com/morluto/gitcontribute/internal/corpus" + "github.com/morluto/gitcontribute/internal/domain" + "github.com/morluto/gitcontribute/internal/evidence" + "github.com/morluto/gitcontribute/internal/investigation" + "github.com/morluto/gitcontribute/internal/mcpcontract" +) + +func TestReconciliationOwnsQueuedJobsAndStopsAbandonedWork(t *testing.T) { + for _, queued := range []bool{false, true} { + t.Run(fmt.Sprintf("queued=%t", queued), func(t *testing.T) { + ctx := context.Background() + svc := newJobTestService(t) + jobs := newJobExecutorOnService(t, svc, jobExecutorConfig{maxConcurrentJobs: 1, heartbeatInterval: time.Hour, pollInterval: 10 * time.Millisecond}) + started, stopped := make(chan struct{}), make(chan struct{}) + running, err := jobs.Submit(ctx, "blocked", nil, func(ctx context.Context, _ func(string, string) error) (any, error) { + close(started) + <-ctx.Done() + close(stopped) + return nil, ctx.Err() + }) + if err != nil { + t.Fatal(err) + } + <-started + id := running + if queued { + id, err = jobs.Submit(ctx, "waiting", nil, func(context.Context, func(string, string) error) (any, error) { + t.Error("abandoned queued work executed") + return struct{}{}, nil + }) + if err != nil { + t.Fatal(err) + } + } + other, err := corpus.Open(ctx, svc.databasePath()) + if err != nil { + t.Fatal(err) + } + defer func() { _ = other.Close() }() + if err := other.ReconcileInterruptedJobs(ctx, time.Minute); err != nil { + t.Fatal(err) + } + live, err := other.GetJob(ctx, id) + if err != nil { + t.Fatal(err) + } + if live.State.Status().Terminal() { + t.Fatalf("live owner's job reconciled: %s", live.State.Status()) + } + if err := other.RegisterJobOwner(ctx, jobs.ownerID, 1, time.Now().Add(-time.Hour)); err != nil { + t.Fatal(err) + } + if err := other.ReconcileInterruptedJobs(ctx, time.Minute); err != nil { + t.Fatal(err) + } + abandoned, err := other.GetJob(ctx, id) + if err != nil { + t.Fatal(err) + } + if abandoned.State.Status() != corpus.JobStatusFailed { + t.Fatalf("abandoned job remains %s", abandoned.State.Status()) + } + select { + case <-stopped: + case <-time.After(time.Second): + t.Fatal("reconciled worker kept running") + } + }) + } +} + +func TestRelatedWorkRejectsUnrelatedFindings(t *testing.T) { + ctx := context.Background() + svc := newLocalService(t) + defer func() { _ = svc.Close() }() + c, err := svc.openCorpus(ctx) + if err != nil { + t.Fatal(err) + } + repo, err := c.UpsertRepository(ctx, corpus.Repository{Owner: "owner", Name: "repo", ExternalID: "ranking"}, "{}") + if err != nil { + t.Fatal(err) + } + now := time.Now().UTC() + for i, title := range []string{"quasar nebula", "orchid nectar", "quasar detector"} { + _, err := c.UpsertThread(ctx, corpus.Thread{RepositoryID: repo.ID, Kind: domain.PullRequestKind, Number: i + 1, State: "open", Title: title, SourceCreatedAt: now, SourceUpdatedAt: now}, "{}") + if err != nil { + t.Fatal(err) + } + } + inv, err := svc.StartInvestigation(ctx, contracts.RepoRef{Owner: "owner", Repo: "repo"}, "commit", "") + if err != nil { + t.Fatal(err) + } + h, err := svc.CreateHypothesis(ctx, inv.ID, investigation.CreateHypothesisInput{Title: "quasar nebula", Description: "", Category: investigation.CategoryBug}) + if err != nil { + t.Fatal(err) + } + dup, err := svc.CheckHypothesisDuplicates(ctx, h.ID, 10) + if err != nil { + t.Fatal(err) + } + col, err := svc.CheckHypothesisCollisions(ctx, h.ID, 10) + if err != nil { + t.Fatal(err) + } + for name, findings := range map[string][]evidence.Evidence{"duplicates": dup.Findings, "collisions": col.Findings} { + if len(findings) != 2 { + t.Errorf("%s returned %d findings, want exact and weak positive matches only", name, len(findings)) + } + for _, f := range findings { + if strings.Contains(f.Description, "orchid nectar") { + t.Errorf("%s includes unrelated finding: %s", name, f.Description) + } + if f.Relation != evidence.RelationInconclusive { + t.Errorf("%s lexical candidate claims %s evidence", name, f.Relation) + } + } + if len(findings) > 0 && !strings.Contains(findings[0].Description, "quasar nebula") { + t.Errorf("%s exact title was not first", name) + } + } +} + +func TestRelatedWorkDoesNotHideCandidateBound(t *testing.T) { + ctx := context.Background() + svc := newLocalService(t) + defer func() { _ = svc.Close() }() + c, err := svc.openCorpus(ctx) + if err != nil { + t.Fatal(err) + } + repo, err := c.UpsertRepository(ctx, corpus.Repository{Owner: "owner", Name: "repo", ExternalID: "bounded-ranking"}, "{}") + if err != nil { + t.Fatal(err) + } + now := time.Now().UTC() + for i := 1; i <= minCandidateLimit+1; i++ { + title := "orchid nectar" + if i == 1 { + title = "quasar nebula" + } + if _, err := c.UpsertThread(ctx, corpus.Thread{RepositoryID: repo.ID, Kind: domain.PullRequestKind, Number: i, State: "open", Title: title, SourceCreatedAt: now, SourceUpdatedAt: now}, "{}"); err != nil { + t.Fatal(err) + } + } + if err := c.AdvanceFacet(ctx, repo.ID, nil, "threads", now, true, 0); err != nil { + t.Fatal(err) + } + inv, err := svc.StartInvestigation(ctx, contracts.RepoRef{Owner: "owner", Repo: "repo"}, "commit", "") + if err != nil { + t.Fatal(err) + } + h, err := svc.CreateHypothesis(ctx, inv.ID, investigation.CreateHypothesisInput{Title: "quasar nebula", Category: investigation.CategoryBug}) + if err != nil { + t.Fatal(err) + } + out, err := (&MCPReader{svc}).CheckDuplicates(ctx, mcpcontract.CheckDuplicatesInput{Target: "hypothesis", ID: h.ID, Limit: 10}) + if err != nil { + t.Fatal(err) + } + if out.Status != "partial" || !out.Truncated || out.Recovery == nil { + t.Fatalf("bounded empty result claims completeness: %+v", out) + } + larger, err := (&MCPReader{svc}).CheckDuplicates(ctx, mcpcontract.CheckDuplicatesInput{Target: "hypothesis", ID: h.ID, Limit: 20}) + if err != nil { + t.Fatal(err) + } + if larger.Total != 1 || larger.Truncated { + t.Fatalf("larger bound should recover exact match: %+v", larger) + } +} + +func TestLostOwnerStopsWorkAndAdmission(t *testing.T) { + ctx := context.Background() + svc := newJobTestService(t) + jobs := newJobExecutorOnService(t, svc, jobExecutorConfig{heartbeatInterval: 10 * time.Millisecond}) + started := make(chan struct{}) + id, err := jobs.Submit(ctx, "owner-loss", nil, func(ctx context.Context, _ func(string, string) error) (any, error) { + close(started) + <-ctx.Done() + return nil, ctx.Err() + }) + if err != nil { + t.Fatal(err) + } + <-started + if err := svc.corpus.DeleteJobOwner(ctx, jobs.ownerID); err != nil { + t.Fatal(err) + } + waitForJobStatus(t, jobs, id, corpus.JobStatusCancelled, time.Second) + if _, err := jobs.Submit(ctx, "after-owner-loss", nil, func(context.Context, func(string, string) error) (any, error) { + t.Error("unowned work executed") + return struct{}{}, nil + }); err == nil { + t.Fatal("executor admitted work after losing ownership") + } +} diff --git a/internal/app/duplicates_test.go b/internal/app/duplicates_test.go index c8b87dc9..91c091f5 100644 --- a/internal/app/duplicates_test.go +++ b/internal/app/duplicates_test.go @@ -105,7 +105,7 @@ func TestDuplicateAndCollisionChecks(t *testing.T) { t.Fatalf("collision result = %+v", coll) } for _, f := range coll.Findings { - if f.Relation != evidence.RelationContradicting { + if f.Relation != evidence.RelationInconclusive { t.Fatalf("collision finding should be contradicting, got %q", f.Relation) } } diff --git a/internal/app/job_executor.go b/internal/app/job_executor.go index c089c0ba..8a2e9f4f 100644 --- a/internal/app/job_executor.go +++ b/internal/app/job_executor.go @@ -25,7 +25,7 @@ var ErrJobQueueFull = errors.New("job executor queue is full") type jobStore interface { StoppedJobIDs(context.Context, []string) (map[string]struct{}, error) - CreateJob(context.Context, string, string) (*corpus.Job, error) + CreateJobAs(context.Context, string, string, string) (*corpus.Job, error) DeleteJobOwner(context.Context, string) error GetJob(context.Context, string) (*corpus.Job, error) HeartbeatJobOwner(context.Context, string, time.Time) error @@ -152,6 +152,10 @@ func (e *JobExecutor) Submit(ctx context.Context, kind string, request any, fn J e.mu.Unlock() return "", errors.New("job executor is closed") } + if err := e.rootCtx.Err(); err != nil { + e.mu.Unlock() + return "", err + } if e.admittedCount >= e.cfg.maxAdmittedJobs { e.mu.Unlock() return "", ErrJobQueueFull @@ -165,7 +169,7 @@ func (e *JobExecutor) Submit(ctx context.Context, kind string, request any, fn J return "", fmt.Errorf("marshal job request: %w", err) } - job, err := e.corpus.CreateJob(ctx, kind, string(reqJSON)) + job, err := e.corpus.CreateJobAs(ctx, kind, string(reqJSON), e.ownerID) if err != nil { e.releaseAdmission() return "", err @@ -292,7 +296,8 @@ func (e *JobExecutor) heartbeat() { } if errors.Is(err, corpus.ErrJobOwnerNotFound) || errors.Is(err, context.Canceled) { // The owner row was removed (abandoned) or the executor is shutting - // down; stop heartbeating. + // down; stop work as well as heartbeating. + e.cancel() return } // Wait a full interval after a transient failure. A fixed-rate ticker diff --git a/internal/app/mcp_external_audit_test.go b/internal/app/mcp_external_audit_test.go new file mode 100644 index 00000000..f101096a --- /dev/null +++ b/internal/app/mcp_external_audit_test.go @@ -0,0 +1,137 @@ +package app + +import ( + "context" + "encoding/json" + "strings" + "testing" + + "github.com/modelcontextprotocol/go-sdk/mcp" + "github.com/morluto/gitcontribute/internal/contracts" + "github.com/morluto/gitcontribute/internal/corpus" + "github.com/morluto/gitcontribute/internal/evidence" + "github.com/morluto/gitcontribute/internal/mcpcontract" + "github.com/morluto/gitcontribute/internal/mcpserver" +) + +func connectAuditMCP(t *testing.T, svc *Service) *mcp.ClientSession { + t.Helper() + server, err := mcpserver.New(svc.MCPReader(), "audit-test") + if err != nil { + t.Fatal(err) + } + a, b := mcp.NewInMemoryTransports() + ss, err := server.MCP().Connect(context.Background(), a, nil) + if err != nil { + t.Fatal(err) + } + t.Cleanup(func() { _ = ss.Close() }) + client := mcp.NewClient(&mcp.Implementation{Name: "audit-test", Version: "test"}, nil) + cs, err := client.Connect(context.Background(), b, nil) + if err != nil { + t.Fatal(err) + } + t.Cleanup(func() { _ = cs.Close() }) + return cs +} + +func TestMCPIndexJobDetailedBatchReturnsUsableArtifactReference(t *testing.T) { + ctx := context.Background() + svc := newSearchTestService(t) + job, err := svc.corpus.CreateJob(ctx, "index_repositories", `{}`) + if err != nil { + t.Fatal(err) + } + if err := svc.corpus.StartJob(ctx, job.ID); err != nil { + t.Fatal(err) + } + result := `{"status":"complete","items":[{"key":"acme/rocket","status":"complete","commit_sha":"commit-a","artifact_digest":"` + strings.Repeat("a", 64) + `","manifest_digest":"` + strings.Repeat("b", 64) + `"}]}` + if err := svc.corpus.TransitionJob(ctx, job.ID, corpus.JobRunningToSucceeded, result, ""); err != nil { + t.Fatal(err) + } + session := connectAuditMCP(t, svc) + out := callMCPTool[mcpcontract.GetJobsOutput](ctx, t, session, mcpcontract.ToolGetJob, map[string]any{"ids": []string{job.ID, "missing"}, "response_format": "detailed"}) + if len(out.Items) != 2 || out.Items[0].Value == nil || len(out.Items[0].Value.Artifacts) != 1 || out.Items[1].Status != mcpcontract.BatchItemUnavailable { + t.Fatalf("batch = %+v", out) + } + artifact := out.Items[0].Value.Artifacts[0] + if artifact.URI != "gitcontribute://artifact/code-index/"+strings.Repeat("a", 64) || artifact.CodeIndex == nil || artifact.CodeIndex.CommitSHA != "commit-a" { + t.Fatalf("artifact = %+v", artifact) + } + // A reference must not claim zero indexed files or missing provenance as if + // it were the full indexed-commit manifest. + raw, err := json.Marshal(artifact.CodeIndex) + if err != nil { + t.Fatal(err) + } + var fields map[string]any + if err := json.Unmarshal(raw, &fields); err != nil { + t.Fatal(err) + } + if _, ok := fields["file_count"]; ok { + t.Fatalf("reference contains invented manifest metadata: %s", raw) + } +} + +func TestMCPValidationJobHandsOffReadableAttemptIdentities(t *testing.T) { + ctx := context.Background() + svc := newSearchTestService(t) + inv, err := svc.StartInvestigation(ctx, contracts.RepoRef{Owner: "owner", Repo: "repo"}, "commit-a", "") + if err != nil { + t.Fatal(err) + } + definition := &evidence.ValidationDefinition{ID: "definition", InvestigationID: inv.ID, Command: []string{"git", "diff", "--check"}, WorkingDir: "/private/worktree"} + if err := svc.corpus.SaveValidationDefinition(ctx, definition); err != nil { + t.Fatal(err) + } + group := &evidence.ValidationRunGroup{ID: "group", DefinitionID: definition.ID, InvestigationID: inv.ID, RequestedRuns: 2, CompletedRuns: 2, Classification: evidence.RunGroupStablePass, Attempts: []evidence.ValidationAttempt{ + {Index: 1, Kind: evidence.RunKindBase, RunID: "base-run", Classification: evidence.RunClassificationPassing}, + {Index: 1, Kind: evidence.RunKindCandidate, RunID: "candidate-run", Classification: evidence.RunClassificationPassing}, + }} + if err := svc.corpus.SaveValidationRunGroup(ctx, group); err != nil { + t.Fatal(err) + } + job, err := svc.corpus.CreateJob(ctx, "run_validation_group", `{}`) + if err != nil { + t.Fatal(err) + } + if err := svc.corpus.StartJob(ctx, job.ID); err != nil { + t.Fatal(err) + } + if err := svc.corpus.TransitionJob(ctx, job.ID, corpus.JobRunningToSucceeded, `{"id":"group"}`, ""); err != nil { + t.Fatal(err) + } + session := connectAuditMCP(t, svc) + out := callMCPTool[mcpcontract.GetJobsOutput](ctx, t, session, mcpcontract.ToolGetJob, map[string]any{"ids": []string{job.ID}, "response_format": "detailed"}) + if len(out.Items) != 1 || out.Items[0].Value == nil || len(out.Items[0].Value.Artifacts) != 1 { + t.Fatalf("job = %+v", out) + } + artifact := out.Items[0].Value.Artifacts[0] + if artifact.URI == "" || out.Items[0].Value.FollowUp == nil { + t.Fatalf("validation job has no readable handoff: %+v", out.Items[0].Value) + } + resource, err := session.ReadResource(ctx, &mcp.ReadResourceParams{URI: artifact.URI}) + if err != nil { + t.Fatal(err) + } + var payload struct { + ID string `json:"id"` + Classification string `json:"classification"` + Attempts []struct { + RunID string `json:"run_id"` + Kind string `json:"kind"` + } `json:"attempts"` + } + if len(resource.Contents) != 1 { + t.Fatalf("resource = %+v", resource) + } + if err := json.Unmarshal([]byte(resource.Contents[0].Text), &payload); err != nil { + t.Fatal(err) + } + if payload.ID != "group" || payload.Classification != "stable_pass" || len(payload.Attempts) != 2 || payload.Attempts[0].RunID != "base-run" || payload.Attempts[1].RunID != "candidate-run" { + t.Fatalf("group resource = %+v", payload) + } + if strings.Contains(resource.Contents[0].Text, "/private/worktree") { + t.Fatal("resource exposed host path") + } +} diff --git a/internal/app/mcp_github_acquisition.go b/internal/app/mcp_github_acquisition.go index 883d1846..e0a707b2 100644 --- a/internal/app/mcp_github_acquisition.go +++ b/internal/app/mcp_github_acquisition.go @@ -473,6 +473,7 @@ func (r *MCPReader) persistSourceBundle(ctx context.Context, in mcpcontract.Read artifact.Completeness.RequestedItems = len(result.Items) artifact.Completeness.Status = out.Status artifact.Completeness.ContentsBounded = true + out.Completeness = artifact.Completeness materialization, err := corpus.NewSnapshotMaterialization( sourceBundleArtifactKind, sourceBundleSnapshotScope{Repository: in.Repository.Owner + "/" + in.Repository.Repo, RequestedRef: in.Ref, Paths: sourceBundlePaths(in.Files)}, diff --git a/internal/app/mcp_github_acquisition_test.go b/internal/app/mcp_github_acquisition_test.go index 68d0b47f..cb1caf3c 100644 --- a/internal/app/mcp_github_acquisition_test.go +++ b/internal/app/mcp_github_acquisition_test.go @@ -163,6 +163,10 @@ func TestMCPReaderReadSourceFilesStoresCommitAndBlobProvenanceAndReadsLocally(t if err != nil { t.Fatal(err) } + wantCompleteness := mcpcontract.SourceBundleCompleteness{Status: "partial", RequestedItems: 2, CompleteItems: 1, FailedItems: 1, ContentsBounded: true} + if out.Completeness != wantCompleteness || out.Completeness != artifact.Completeness { + t.Fatalf("source response completeness = %+v, artifact = %+v", out.Completeness, artifact.Completeness) + } if artifact.SchemaVersion != sourceBundleArtifactKind || artifact.CommitSHA != "commit-9" || artifact.Items[0].Value == nil || artifact.Items[0].Value.Content != "second\n" || artifact.Items[0].Value.ContentSHA256 == "" || artifact.Items[1].Status != "not_found" { t.Fatalf("source artifact = %+v", artifact) } diff --git a/internal/app/mcp_job_artifacts.go b/internal/app/mcp_job_artifacts.go index 9bd437f3..1b2c17c8 100644 --- a/internal/app/mcp_job_artifacts.go +++ b/internal/app/mcp_job_artifacts.go @@ -3,6 +3,7 @@ package app import ( "encoding/json" "fmt" + "net/url" "strconv" "strings" @@ -76,6 +77,10 @@ func validationJobArtifact(job *contracts.JobResult, kind string) ([]mcpcontract if json.Unmarshal([]byte(job.Result), &result) != nil || result.ID == "" { return nil, nil } + if kind == "validation_group" { + uri := "gitcontribute://validation-group/" + url.PathEscape(result.ID) + return []mcpcontract.JobArtifactReference{{Kind: kind, ID: result.ID, URI: uri}}, resourceFollowUp(uri, "Read execution outcomes and exact attempt run IDs before attaching test reports.") + } return []mcpcontract.JobArtifactReference{{Kind: kind, ID: result.ID}}, nil } @@ -495,7 +500,7 @@ func indexRepositoriesJobArtifact(job *contracts.JobResult) ([]mcpcontract.JobAr continue } completed++ - artifact := mcpcontract.CodeIndexArtifact{Kind: "code_index", ID: "code-index:" + item.ArtifactDigest, + artifact := mcpcontract.CodeIndexArtifactReference{Kind: "code_index", ID: "code-index:" + item.ArtifactDigest, Repository: mcpcontract.RepositoryRef{Owner: owner, Repo: repo}, CommitSHA: item.CommitSHA, SnapshotToken: item.SnapshotToken, ManifestSHA256: item.ManifestDigest, ResourceURI: "gitcontribute://artifact/code-index/" + item.ArtifactDigest} diff --git a/internal/app/mcp_recovery_test.go b/internal/app/mcp_recovery_test.go index dd3a5724..179bbcf3 100644 --- a/internal/app/mcp_recovery_test.go +++ b/internal/app/mcp_recovery_test.go @@ -3,8 +3,10 @@ package app import ( "context" "testing" + "time" "github.com/morluto/gitcontribute/internal/contracts" + "github.com/morluto/gitcontribute/internal/corpus" "github.com/morluto/gitcontribute/internal/investigation" "github.com/morluto/gitcontribute/internal/mcpcontract" ) @@ -76,3 +78,42 @@ func assertRelatedWorkRecovery(t *testing.T, output mcpcontract.CheckOutput, kin t.Fatalf("%s recovery = %+v", kind, output.Recovery) } } + +func TestMCPRelatedWorkPreservesUnknownThreadCoverage(t *testing.T) { + for _, coverage := range []string{"missing", "incomplete", "complete"} { + t.Run(coverage, func(t *testing.T) { + ctx := context.Background() + svc := newSearchTestService(t) + repo, err := svc.corpus.UpsertRepository(ctx, corpus.Repository{Owner: "owner", Name: "repo"}, `{}`) + if err != nil { + t.Fatal(err) + } + if coverage != "missing" { + if err := svc.corpus.AdvanceFacet(ctx, repo.ID, nil, "threads", time.Now(), coverage == "complete", 0); err != nil { + t.Fatal(err) + } + } + inv, err := svc.StartInvestigation(ctx, contracts.RepoRef{Owner: "owner", Repo: "repo"}, "abc", "") + if err != nil { + t.Fatal(err) + } + hypothesis, err := svc.CreateHypothesis(ctx, inv.ID, investigation.CreateHypothesisInput{Title: "parser", Description: "cancellation", Category: investigation.CategoryBug}) + if err != nil { + t.Fatal(err) + } + for _, tool := range []string{"corpus.find_duplicates", "corpus.find_competing_pull_requests"} { + session := connectAuditMCP(t, svc) + out := callMCPTool[mcpcontract.CheckOutput](ctx, t, session, tool, map[string]any{"target": "hypothesis", "id": hypothesis.ID, "limit": 10}) + if coverage == "complete" { + if out.Coverage != "complete" { + t.Fatalf("complete corpus: %+v", out) + } + continue + } + if out.Coverage == "complete" || out.Status == "complete" || out.Recovery == nil { + t.Fatalf("incomplete corpus became negative evidence: %+v", out) + } + } + }) + } +} diff --git a/internal/app/mcp_related_work.go b/internal/app/mcp_related_work.go index 93b462ad..d019add4 100644 --- a/internal/app/mcp_related_work.go +++ b/internal/app/mcp_related_work.go @@ -51,7 +51,7 @@ func (r *MCPReader) checkRelatedWork(ctx context.Context, subject relatedWorkSub repo := subject.investigation.Repo target := subject.kind.String() id := subject.id - indexed, err := r.relatedWorkRepositoryIndexed(ctx, repo) + indexed, complete, err := r.relatedWorkRepositoryCoverage(ctx, repo) if err != nil { return mcpcontract.CheckOutput{}, err } @@ -79,11 +79,17 @@ func (r *MCPReader) checkRelatedWork(ctx context.Context, subject relatedWorkSub if errors.Is(err, errRepositoryNotFound) { return unavailableRelatedWorkOutput(target, id, repo, limit, "repository_not_indexed", message, syncRepositoryContextCall(repo.Owner(), repo.Repo())), nil } + if err == nil && !complete { + result.Status, result.Coverage = "partial", "unknown" + result.Recovery = recoveryPlan("thread_coverage_incomplete", "Stored thread coverage is missing or incomplete. Synchronize repository threads, poll the job, and repeat this check before inferring absence.", mcpcontract.RecoveryAction(mcpcontract.SyncThreadsInput{ + Selection: "repositories", Repositories: []mcpcontract.RepositoryRef{{Owner: repo.Owner(), Repo: repo.Repo()}}, Kind: "both", State: "all", + })) + } return result, err } func duplicateCheckResultToMCP(subject relatedWorkSubject, result *contracts.DuplicateCheckResult) mcpcontract.CheckOutput { - truncated := result.Total >= result.Limit + truncated := result.Truncated var recovery *mcpcontract.RecoveryPlan if truncated { recovery = relatedWorkLimitRecovery(subject, result.Limit, duplicateRelatedWork) @@ -108,7 +114,7 @@ func duplicateCheckResultToMCP(subject relatedWorkSubject, result *contracts.Dup func collisionCheckResultToMCP(subject relatedWorkSubject, result *contracts.CollisionCheckResult) mcpcontract.CheckOutput { findings := make([]evidence.Evidence, len(result.Findings)) copy(findings, result.Findings) - truncated := result.Total >= result.Limit + truncated := result.Truncated var recovery *mcpcontract.RecoveryPlan if truncated { recovery = relatedWorkLimitRecovery(subject, result.Limit, competingPullRequests) @@ -131,7 +137,10 @@ func collisionCheckResultToMCP(subject relatedWorkSubject, result *contracts.Col } func relatedWorkLimitRecovery(subject relatedWorkSubject, limit int, check relatedWorkCheckKind) *mcpcontract.RecoveryPlan { - nextLimit := min(100, max(limit*2, limit+1)) + if limit >= maxResultLimit { + return recoveryPlan("related_work_truncated", "The related-work check reached its maximum bound. Use targeted thread search and inspect exact candidates; this result does not establish absence.") + } + nextLimit := min(maxResultLimit, max(limit*2, limit+1)) message := "The related-work result reached its bound. Rerun the same exact check with a larger limit before treating the findings as exhaustive." input := mcpcontract.CheckDuplicatesInput{Target: subject.kind.String(), ID: subject.id, Limit: nextLimit} if check == competingPullRequests { @@ -140,16 +149,20 @@ func relatedWorkLimitRecovery(subject relatedWorkSubject, limit int, check relat return recoveryPlan("related_work_truncated", message, mcpcontract.RecoveryAction(input)) } -func (r *MCPReader) relatedWorkRepositoryIndexed(ctx context.Context, repo domain.RepoRef) (bool, error) { +func (r *MCPReader) relatedWorkRepositoryCoverage(ctx context.Context, repo domain.RepoRef) (indexed, complete bool, err error) { c, err := r.openReadOnlyCorpus(ctx) if err != nil { - return false, err + return false, false, err } stored, err := c.GetRepository(ctx, repo.Owner(), repo.Repo()) + if err != nil || stored == nil { + return false, false, err + } + coverage, err := c.GetCoverage(ctx, stored.ID, nil, "threads") if err != nil { - return false, err + return true, false, err } - return stored != nil, nil + return true, coverage != nil && coverage.Complete, nil } func unavailableRelatedWorkOutput(target, id string, repo domain.RepoRef, limit int, reason, message string, action mcpcontract.ToolCall) mcpcontract.CheckOutput { diff --git a/internal/app/mcp_validation_resources.go b/internal/app/mcp_validation_resources.go new file mode 100644 index 00000000..c0e14b1a --- /dev/null +++ b/internal/app/mcp_validation_resources.go @@ -0,0 +1,39 @@ +package app + +import ( + "context" + "errors" + + "github.com/morluto/gitcontribute/internal/evidence" + "github.com/morluto/gitcontribute/internal/mcpcontract" +) + +// ValidationGroupResource reads the persisted execution group without running +// validation again. Attempt IDs can be used to attach independently supplied reports. +func (r *MCPReader) ValidationGroupResource(ctx context.Context, id string) (mcpcontract.ValidationGroupResource, error) { + c, err := r.openReadOnlyCorpus(ctx) + if err != nil { + return mcpcontract.ValidationGroupResource{}, err + } + group, err := c.GetValidationRunGroup(ctx, id) + if errors.Is(err, evidence.ErrNotFound) { + return mcpcontract.ValidationGroupResource{}, mcpcontract.ErrNotFound + } + if err != nil { + return mcpcontract.ValidationGroupResource{}, err + } + out := mcpcontract.ValidationGroupResource{ + ID: group.ID, DefinitionID: group.DefinitionID, InvestigationID: group.InvestigationID, ConfigurationSHA256: group.ConfigurationSHA256, + RequestedRuns: group.RequestedRuns, CompletedRuns: group.CompletedRuns, Classification: string(group.Classification), + StartedAt: formatTime(group.StartedAt), CompletedAt: formatTime(group.CompletedAt), + Attempts: make([]mcpcontract.ValidationAttemptResource, len(group.Attempts)), + } + for i, attempt := range group.Attempts { + out.Attempts[i] = mcpcontract.ValidationAttemptResource{ + Index: attempt.Index, Kind: string(attempt.Kind), RunID: attempt.RunID, Classification: string(attempt.Classification), + ObservationStatus: string(attempt.ObservationStatus), ExitCode: attempt.ExitCode, TimeoutPhase: string(attempt.TimeoutPhase), FailurePhase: string(attempt.FailurePhase), + StartedAt: formatTime(attempt.StartedAt), CompletedAt: formatTime(attempt.CompletedAt), + } + } + return out, nil +} diff --git a/internal/app/neighbors_related_work.go b/internal/app/neighbors_related_work.go index ae40e7e2..8c19b0fd 100644 --- a/internal/app/neighbors_related_work.go +++ b/internal/app/neighbors_related_work.go @@ -91,12 +91,12 @@ func (s *Service) loadRelatedWorkSubject(ctx context.Context, kind relatedWorkSu } func (s *Service) duplicatesForRelatedWorkSubject(ctx context.Context, subject relatedWorkSubject, limit int) (*contracts.DuplicateCheckResult, error) { - neighbors, revision, effectiveLimit, err := s.findSimilarThreads(ctx, subject.investigation.Repo, subject.query, allSimilarThreads, limit) + matches, err := s.findSimilarThreads(ctx, subject.investigation.Repo, subject.query, allSimilarThreads, limit) if err != nil { return nil, err } - findings := make([]evidence.Evidence, 0, len(neighbors)) - for _, n := range neighbors { + findings := make([]evidence.Evidence, 0, len(matches.Neighbors)) + for _, n := range matches.Neighbors { findings = append(findings, evidenceFromNeighbor(n, subject.investigation.Repo, subject.investigation.ID, subject.hypothesisID, subject.opportunityID, evidence.RelationInconclusive)) } hypothesisID := "" @@ -109,8 +109,9 @@ func (s *Service) duplicatesForRelatedWorkSubject(ctx context.Context, subject r Repo: subject.investigation.Repo, Query: subject.query.Title, Findings: findings, - SourceRevision: revision, - Limit: effectiveLimit, + SourceRevision: matches.SourceRevision, + Limit: matches.Limit, + Truncated: matches.Truncated, Total: len(findings), }, nil } @@ -156,13 +157,13 @@ func (s *Service) CheckOpportunityCollisions(ctx context.Context, opportunityID } func (s *Service) collisionsForRelatedWorkSubject(ctx context.Context, subject relatedWorkSubject, limit int) (*contracts.CollisionCheckResult, error) { - neighbors, revision, effectiveLimit, err := s.findSimilarThreads(ctx, subject.investigation.Repo, subject.query, openPullRequestsOnly, limit) + matches, err := s.findSimilarThreads(ctx, subject.investigation.Repo, subject.query, openPullRequestsOnly, limit) if err != nil { return nil, err } - findings := make([]evidence.Evidence, 0, len(neighbors)) - for _, n := range neighbors { - findings = append(findings, evidenceFromNeighbor(n, subject.investigation.Repo, subject.investigation.ID, subject.hypothesisID, subject.opportunityID, evidence.RelationContradicting)) + findings := make([]evidence.Evidence, 0, len(matches.Neighbors)) + for _, n := range matches.Neighbors { + findings = append(findings, evidenceFromNeighbor(n, subject.investigation.Repo, subject.investigation.ID, subject.hypothesisID, subject.opportunityID, evidence.RelationInconclusive)) } return &contracts.CollisionCheckResult{ HypothesisID: subject.hypothesisID, @@ -170,8 +171,9 @@ func (s *Service) collisionsForRelatedWorkSubject(ctx context.Context, subject r Repo: subject.investigation.Repo, Query: subject.query.Title, Findings: findings, - SourceRevision: revision, - Limit: effectiveLimit, + SourceRevision: matches.SourceRevision, + Limit: matches.Limit, + Truncated: matches.Truncated, Total: len(findings), }, nil } @@ -190,31 +192,39 @@ func (s similarThreadScope) filters() (corpus.ThreadKindFilter, corpus.ThreadSta return corpus.AnyThreadKind(), corpus.AnyThreadState() } -func (s *Service) findSimilarThreads(ctx context.Context, repo domain.RepoRef, query clustering.Candidate, scope similarThreadScope, limit int) ([]clustering.Neighbor, string, int, error) { +type similarThreadsResult struct { + Neighbors []clustering.Neighbor + SourceRevision string + Limit int + Truncated bool +} + +func (s *Service) findSimilarThreads(ctx context.Context, repo domain.RepoRef, query clustering.Candidate, scope similarThreadScope, limit int) (similarThreadsResult, error) { if !repo.IsValid() { - return nil, "", 0, errors.New("repository is required") + return similarThreadsResult{}, errors.New("repository is required") } limit, err := normalizeSimilarityLimit(limit) if err != nil { - return nil, "", 0, err + return similarThreadsResult{}, err } c, err := s.openReadOnlyCorpus(ctx) if err != nil { - return nil, "", 0, err + return similarThreadsResult{}, err } repository, err := c.GetRepository(ctx, repo.Owner(), repo.Repo()) if err != nil { - return nil, "", 0, err + return similarThreadsResult{}, err } if repository == nil { // No local corpus data for this repository; return an empty result without // performing network access. - return nil, "", limit, nil + return similarThreadsResult{Limit: limit}, nil } kind, state := scope.filters() - threads, err := c.ListThreadsFiltered(ctx, repository.ID, kind, state, similarityCandidateLimit(limit)) + candidateLimit := similarityCandidateLimit(limit) + threads, err := c.ListThreadsFiltered(ctx, repository.ID, kind, state, candidateLimit) if err != nil { - return nil, "", 0, err + return similarThreadsResult{}, err } candidates := make([]clustering.Candidate, 0, len(threads)) for _, t := range threads { @@ -223,9 +233,18 @@ func (s *Service) findSimilarThreads(ctx context.Context, repo domain.RepoRef, q all := append([]clustering.Candidate{query}, candidates...) neighbors, err := clustering.Neighbors(ctx, query, candidates, limit) if err != nil { - return nil, "", 0, err + return similarThreadsResult{}, err + } + // A bounded population is unknown even if none of the scored candidates + // has signal. Keep this separate from the displayed finding count. + positive := neighbors[:0] + for _, n := range neighbors { + if n.Score > 0 { + positive = append(positive, n) + } } - return neighbors, clustering.SourceRevision(all), limit, nil + truncated := len(threads) >= candidateLimit || len(positive) >= limit + return similarThreadsResult{Neighbors: positive, SourceRevision: clustering.SourceRevision(all), Limit: limit, Truncated: truncated}, nil } func normalizeSimilarityLimit(limit int) (int, error) { diff --git a/internal/contracts/workflow_service.go b/internal/contracts/workflow_service.go index 34bbebf7..baf1f94d 100644 --- a/internal/contracts/workflow_service.go +++ b/internal/contracts/workflow_service.go @@ -55,6 +55,7 @@ type DuplicateCheckResult struct { SourceRevision string `json:"source_revision"` Limit int `json:"limit"` Total int `json:"total"` + Truncated bool `json:"truncated"` } type CollisionCheckResult struct { @@ -66,6 +67,7 @@ type CollisionCheckResult struct { SourceRevision string `json:"source_revision"` Limit int `json:"limit"` Total int `json:"total"` + Truncated bool `json:"truncated"` } type PrepareReviewReportInput struct { diff --git a/internal/corpus/jobs.go b/internal/corpus/jobs.go index 133f334e..a812d181 100644 --- a/internal/corpus/jobs.go +++ b/internal/corpus/jobs.go @@ -21,6 +21,12 @@ var ErrJobOwnerNotFound = errors.New("job owner not found") // CreateJob creates a new job in the queued state with an opaque stable ID. func (c *Corpus) CreateJob(ctx context.Context, kind, request string) (*Job, error) { + return c.CreateJobAs(ctx, kind, request, "") +} + +// CreateJobAs atomically persists queued work with its executor owner so a +// restart can distinguish live admission from an abandoned queue. +func (c *Corpus) CreateJobAs(ctx context.Context, kind, request, ownerID string) (*Job, error) { if strings.TrimSpace(kind) == "" { return nil, errors.New("job kind is required") } @@ -30,9 +36,9 @@ func (c *Corpus) CreateJob(ctx context.Context, kind, request string) (*Job, err now := time.Now().UTC() id := uuid.NewString() if _, err := c.db.ExecContext(ctx, ` - INSERT INTO jobs (id, kind, status, request, created_at, updated_at) - VALUES (?, ?, ?, ?, ?, ?) - `, id, kind, JobStatusQueued, request, encodeTime(now), encodeTime(now)); err != nil { + INSERT INTO jobs (id, kind, status, request, created_at, updated_at, owner_id) + VALUES (?, ?, ?, ?, ?, ?, NULLIF(?, '')) + `, id, kind, JobStatusQueued, request, encodeTime(now), encodeTime(now), ownerID); err != nil { return nil, fmt.Errorf("create job: %w", err) } return c.GetJob(ctx, id) @@ -51,8 +57,8 @@ func (c *Corpus) GetJob(ctx context.Context, id string) (*Job, error) { return job, nil } -// StoppedJobIDs returns job IDs with a persisted cancellation request or no -// durable row. Workers must stop in either case. +// StoppedJobIDs returns job IDs that are terminal, cancelled, or missing. +// Workers must stop when another executor has reconciled their durable state. func (c *Corpus) StoppedJobIDs(ctx context.Context, ids []string) (_ map[string]struct{}, err error) { stopped := make(map[string]struct{}) if len(ids) == 0 { @@ -64,7 +70,7 @@ func (c *Corpus) StoppedJobIDs(ctx context.Context, ids []string) (_ map[string] args[i] = ids[i] } rows, err := c.db.QueryContext(ctx, ` - SELECT id, cancelled_at + SELECT id, cancelled_at, status FROM jobs WHERE id IN (`+placeholders+`) `, args...) @@ -80,11 +86,12 @@ func (c *Corpus) StoppedJobIDs(ctx context.Context, ids []string) (_ map[string] for rows.Next() { var id string var cancelledAt sql.NullInt64 - if err := rows.Scan(&id, &cancelledAt); err != nil { + var status JobStatus + if err := rows.Scan(&id, &cancelledAt, &status); err != nil { return nil, err } found[id] = struct{}{} - if cancelledAt.Valid { + if cancelledAt.Valid || status.Terminal() { stopped[id] = struct{}{} } } @@ -201,7 +208,8 @@ func (c *Corpus) StartJobAs(ctx context.Context, id, ownerID string) error { UPDATE jobs SET status = ?, started_at = ?, updated_at = ?, owner_id = NULLIF(?, '') WHERE id = ? AND status = ? AND COALESCE(cancelled_at, 0) = 0 - `, JobStatusRunning, encodeTime(now), encodeTime(now), ownerID, id, JobStatusQueued) + AND (owner_id IS NULL OR owner_id = ?) + `, JobStatusRunning, encodeTime(now), encodeTime(now), ownerID, id, JobStatusQueued, ownerID) if err != nil { return fmt.Errorf("start job: %w", err) } @@ -392,7 +400,7 @@ func (c *Corpus) ListJobEvents(ctx context.Context, jobID string) ([]JobEvent, e return out, rows.Err() } -// ReconcileInterruptedJobs marks running jobs as failed or cancelled when +// ReconcileInterruptedJobs marks queued and running jobs as failed or cancelled when // their owning process has not heartbeated within leaseTimeout. Live owners // are left untouched, and stale owner records are removed. // @@ -424,8 +432,8 @@ func (c *Corpus) ReconcileInterruptedJobs(ctx context.Context, leaseTimeout time SELECT j.id, j.cancelled_at, j.owner_id, COALESCE(o.heartbeat_at, 0) FROM jobs j LEFT JOIN job_owners o ON j.owner_id = o.owner_id - WHERE j.status = ? - `, JobStatusRunning) + WHERE j.status IN (?, ?) + `, JobStatusQueued, JobStatusRunning) if err != nil { return fmt.Errorf("select interrupted jobs: %w", err) } @@ -467,8 +475,8 @@ func (c *Corpus) ReconcileInterruptedJobs(ctx context.Context, leaseTimeout time if _, err := conn.ExecContext(ctx, ` UPDATE jobs SET status = ?, completed_at = ?, error = ?, updated_at = ?, owner_id = NULL - WHERE id = ? AND status = ? - `, status, nowEncoded, msg, nowEncoded, j.id, JobStatusRunning); err != nil { + WHERE id = ? AND status IN (?, ?) + `, status, nowEncoded, msg, nowEncoded, j.id, JobStatusQueued, JobStatusRunning); err != nil { return fmt.Errorf("reconcile interrupted job %s: %w", j.id, err) } if _, err := conn.ExecContext(ctx, ` diff --git a/internal/corpus/jobs_test.go b/internal/corpus/jobs_test.go index 585a8e43..06dbeb15 100644 --- a/internal/corpus/jobs_test.go +++ b/internal/corpus/jobs_test.go @@ -682,3 +682,26 @@ func TestZeroRowTransitionPropagatesGetJobError(t *testing.T) { t.Fatalf("expected GetJob error to be propagated, got: %v", err) } } + +func TestQueuedJobOwnerCannotBeReplaced(t *testing.T) { + t.Parallel() + ctx := context.Background() + c, _ := openTestCorpus(t) + for _, owner := range []string{"first", "second"} { + if err := c.RegisterJobOwner(ctx, owner, 1, time.Now()); err != nil { + t.Fatal(err) + } + } + job, err := c.CreateJobAs(ctx, "owned", "{}", "first") + if err != nil { + t.Fatal(err) + } + for _, other := range []string{"second", ""} { + if err := c.StartJobAs(ctx, job.ID, other); err == nil { + t.Fatalf("owner %q stole queued work", other) + } + } + if err := c.StartJobAs(ctx, job.ID, "first"); err != nil { + t.Fatal(err) + } +} diff --git a/internal/mcpcontract/operation_contracts.go b/internal/mcpcontract/operation_contracts.go index e8530472..15e7109c 100644 --- a/internal/mcpcontract/operation_contracts.go +++ b/internal/mcpcontract/operation_contracts.go @@ -72,20 +72,20 @@ type GetJobInput struct { // JobArtifactReference identifies a bounded durable result without exposing the // job executor's stored request or result representation. type JobArtifactReference struct { - Kind string `json:"kind" jsonschema:"Artifact kind owned by GitContribute"` - ID string `json:"id,omitempty" jsonschema:"Stable artifact identifier when one exists"` - URI string `json:"uri,omitempty" jsonschema:"MCP resource URI when the artifact is readable as a resource"` - Count *NonNegativeInt `json:"count,omitempty" jsonschema:"Known number of affected objects for a bounded collection, including zero"` - References []string `json:"references,omitempty" jsonschema:"Bounded exact repository, thread, or pull-request references produced by the job"` - ReferencesTruncated bool `json:"references_truncated,omitempty" jsonschema:"Whether more exact references exist than this bounded response includes"` - Failures []JobArtifactFailure `json:"failures,omitempty" jsonschema:"Bounded per-reference outcomes that require retry or recovery"` - FailuresTruncated bool `json:"failures_truncated,omitempty" jsonschema:"Whether more failed outcomes exist than this bounded response includes"` - CodeIndex *CodeIndexArtifact `json:"code_index,omitempty" jsonschema:"Revision-bound indexed-commit artifact"` - Status string `json:"status,omitempty" jsonschema:"Artifact completeness status"` - DiscoveryStatus string `json:"discovery_status,omitempty"` - SearchIncomplete bool `json:"search_incomplete,omitempty"` - RequestCapped bool `json:"request_capped,omitempty"` - Recovery *RecoveryPlan `json:"recovery,omitempty"` + Kind string `json:"kind" jsonschema:"Artifact kind owned by GitContribute"` + ID string `json:"id,omitempty" jsonschema:"Stable artifact identifier when one exists"` + URI string `json:"uri,omitempty" jsonschema:"MCP resource URI when the artifact is readable as a resource"` + Count *NonNegativeInt `json:"count,omitempty" jsonschema:"Known number of affected objects for a bounded collection, including zero"` + References []string `json:"references,omitempty" jsonschema:"Bounded exact repository, thread, or pull-request references produced by the job"` + ReferencesTruncated bool `json:"references_truncated,omitempty" jsonschema:"Whether more exact references exist than this bounded response includes"` + Failures []JobArtifactFailure `json:"failures,omitempty" jsonschema:"Bounded per-reference outcomes that require retry or recovery"` + FailuresTruncated bool `json:"failures_truncated,omitempty" jsonschema:"Whether more failed outcomes exist than this bounded response includes"` + CodeIndex *CodeIndexArtifactReference `json:"code_index,omitempty" jsonschema:"Revision-bound indexed-commit artifact"` + Status string `json:"status,omitempty" jsonschema:"Artifact completeness status"` + DiscoveryStatus string `json:"discovery_status,omitempty"` + SearchIncomplete bool `json:"search_incomplete,omitempty"` + RequestCapped bool `json:"request_capped,omitempty"` + Recovery *RecoveryPlan `json:"recovery,omitempty"` } // JobArtifactFailure preserves one actionable item-level outcome without diff --git a/internal/mcpcontract/scalable_contracts.go b/internal/mcpcontract/scalable_contracts.go index f6a393fe..af1c5700 100644 --- a/internal/mcpcontract/scalable_contracts.go +++ b/internal/mcpcontract/scalable_contracts.go @@ -460,6 +460,19 @@ type IndexRepositoriesInput struct { Repositories []IndexRepositoryInput `json:"repositories" jsonschema:"One to 10 repositories to acquire and index"` } +// CodeIndexArtifactReference carries only facts available in a completed job. +// Full manifest metadata is owned by the exact resource at ResourceURI. +type CodeIndexArtifactReference struct { + Kind string `json:"kind"` + ID string `json:"id"` + Repository RepositoryRef `json:"repository"` + CommitSHA string `json:"commit_sha"` + ManifestSHA256 string `json:"manifest_sha256"` + SnapshotToken string `json:"snapshot_token"` + ResourceURI string `json:"resource_uri"` + FollowUp *JobFollowUp `json:"follow_up"` +} + // CodeIndexArtifact is the typed, revision-bound handoff for one immutable // indexed commit. The resource URI is canonical; callers must consume it with // MCP resources/read rather than reconstructing a larger payload from fields. diff --git a/internal/mcpcontract/validation_resources.go b/internal/mcpcontract/validation_resources.go new file mode 100644 index 00000000..d537dad1 --- /dev/null +++ b/internal/mcpcontract/validation_resources.go @@ -0,0 +1,29 @@ +package mcpcontract + +// ValidationGroupResource exposes persisted execution outcomes and exact run +// identities without leaking commands, environment values, or host paths. +type ValidationGroupResource struct { + ID string `json:"id"` + DefinitionID string `json:"definition_id"` + InvestigationID string `json:"investigation_id"` + ConfigurationSHA256 string `json:"configuration_sha256"` + RequestedRuns int `json:"requested_runs"` + CompletedRuns int `json:"completed_runs"` + Classification string `json:"classification"` + StartedAt string `json:"started_at"` + CompletedAt string `json:"completed_at"` + Attempts []ValidationAttemptResource `json:"attempts"` +} + +type ValidationAttemptResource struct { + Index int `json:"index"` + Kind string `json:"kind"` + RunID string `json:"run_id"` + Classification string `json:"classification"` + ObservationStatus string `json:"observation_status,omitempty"` + ExitCode int `json:"exit_code"` + TimeoutPhase string `json:"timeout_phase,omitempty"` + FailurePhase string `json:"failure_phase,omitempty"` + StartedAt string `json:"started_at"` + CompletedAt string `json:"completed_at"` +} diff --git a/internal/mcpserver/resource_templates.go b/internal/mcpserver/resource_templates.go index 3f21f255..bee94232 100644 --- a/internal/mcpserver/resource_templates.go +++ b/internal/mcpserver/resource_templates.go @@ -73,6 +73,12 @@ func (s *Server) registerResourceTemplates() { name: "Manifest", description: "Persisted contribution evidence manifest", }) } + if _, ok := s.reader.(validationGroupResourceReader); ok { + templates = append(templates, resourceTemplateDefinition{ + template: "gitcontribute://validation-group/{id}", + name: "Validation group", description: "Persisted execution outcomes and exact validation run IDs; no execution", + }) + } if _, ok := s.reader.(workspaceResourceReader); ok { templates = append(templates, resourceTemplateDefinition{ template: "gitcontribute://workspace/{id}", diff --git a/internal/mcpserver/resources.go b/internal/mcpserver/resources.go index 40c321b9..01d17c10 100644 --- a/internal/mcpserver/resources.go +++ b/internal/mcpserver/resources.go @@ -12,6 +12,10 @@ import ( "github.com/morluto/gitcontribute/internal/mcpcontract" ) +type validationGroupResourceReader interface { + ValidationGroupResource(context.Context, string) (mcpcontract.ValidationGroupResource, error) +} + type concernResourceReader interface { Concern(context.Context, mcpcontract.ConcernInput) (mcpcontract.ConcernOutput, error) } @@ -133,6 +137,8 @@ func (s *Server) readResourceValue(ctx context.Context, req resourceRequest) (an return s.readDraftResource(ctx, req) case "manifest": return s.readManifestResource(ctx, req) + case "validation-group": + return s.readValidationGroupResource(ctx, req) case "workspace": return s.readWorkspaceResource(ctx, req) case "pull-request-feedback": @@ -412,3 +418,14 @@ func evidenceResourceInput(_ string, parts []string) (mcpcontract.EvidenceInput, in.Limit = 100 return in, true } + +func (s *Server) readValidationGroupResource(ctx context.Context, req resourceRequest) (mcpcontract.ValidationGroupResource, error) { + if len(req.parts) != 1 || strings.TrimSpace(req.parts[0]) == "" { + return mcpcontract.ValidationGroupResource{}, mcp.ResourceNotFoundError(req.uri) + } + reader, ok := s.reader.(validationGroupResourceReader) + if !ok { + return mcpcontract.ValidationGroupResource{}, mcp.ResourceNotFoundError(req.uri) + } + return reader.ValidationGroupResource(ctx, req.parts[0]) +} From 7ebb1fc3e12e24a16cab94b6abcbabc06e504082 Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Tue, 8 Sep 2026 09:03:27 +0800 Subject: [PATCH 4/4] chore(deps): bump Go MCP SDK to v1.8.0-pre.2 --- docs/concurrency-ranking-audit.md | 11 ++++++----- go.mod | 2 +- go.sum | 4 ++-- 3 files changed, 9 insertions(+), 8 deletions(-) diff --git a/docs/concurrency-ranking-audit.md b/docs/concurrency-ranking-audit.md index 73e83d94..f8e3bbed 100644 --- a/docs/concurrency-ranking-audit.md +++ b/docs/concurrency-ranking-audit.md @@ -2,7 +2,7 @@ ## Need for jobs and SDK support -GitContribute already uses the latest stable official Go MCP SDK, **v1.7.0** +At the start of this audit, GitContribute used the latest stable official Go MCP SDK, **v1.7.0** (released July 28). The newest prerelease checked was **v1.8.0-pre.2** (September 4). Both the Go module registry and GitHub release metadata were checked, and both versions' source was inspected. Neither supplies a task runtime or `TaskStore` @@ -17,9 +17,9 @@ cooperative cancellation. Servers still own durable creation and execution; clients must opt into the extension. Protocol support would replace an adapter surface, not SQLite persistence, admission limits, or process ownership. Retain the executor for acquisition, indexing, and validation; ordinary bounded -reads stay synchronous. No second task implementation or prerelease upgrade was -added. The prerelease's cancellation and teardown fixes merit a separate upgrade -evaluation when adopting it. +reads stay synchronous. No second task implementation was added. The subsequent +SDK update adopts **v1.8.0-pre.2**, including its cancellation and teardown fixes; +the task-runtime assessment above still applies. [Tasks extension](https://modelcontextprotocol.io/extensions/tasks/overview). ## Reproduced defects and corrections @@ -103,4 +103,5 @@ go test -race -short -p=1 -parallel=4 -count=1 -timeout 120s ./internal/app ./in The external workload preceded the dependency update. Final tests cover the updated dependency, but the external multi-process probe was not repeated after -its task-owned runtime was removed. The Go MCP SDK version did not change. +its task-owned runtime was removed. These audit runs preceded the subsequent +Go MCP SDK update to v1.8.0-pre.2. diff --git a/go.mod b/go.mod index 31c452c6..0cb5206d 100644 --- a/go.mod +++ b/go.mod @@ -11,7 +11,7 @@ require ( github.com/google/jsonschema-go v0.4.3 github.com/google/shlex v0.0.0-20191202100458-e7afc7fbc510 github.com/google/uuid v1.6.0 - github.com/modelcontextprotocol/go-sdk v1.7.0 + github.com/modelcontextprotocol/go-sdk v1.8.0-pre.2 github.com/pelletier/go-toml/v2 v2.4.3 github.com/pressly/goose/v3 v3.27.3 github.com/sethvargo/go-retry v0.4.0 diff --git a/go.sum b/go.sum index 488e5950..ae5b1e47 100644 --- a/go.sum +++ b/go.sum @@ -98,8 +98,8 @@ github.com/mfridman/interpolate v0.0.2 h1:pnuTK7MQIxxFz1Gr+rjSIx9u7qVjf5VOoM/u6B github.com/mfridman/interpolate v0.0.2/go.mod h1:p+7uk6oE07mpE/Ik1b8EckO0O4ZXiGAfshKBWLUM9Xg= github.com/mitchellh/hashstructure/v2 v2.0.2 h1:vGKWl0YJqUNxE8d+h8f6NJLcCJrgbhC4NcD46KavDd4= github.com/mitchellh/hashstructure/v2 v2.0.2/go.mod h1:MG3aRVU/N29oo/V/IhBX8GR/zz4kQkprJgF2EVszyDE= -github.com/modelcontextprotocol/go-sdk v1.7.0 h1:yqjY2dsbKAC0LSuWZVBMrHgiG8ukXv6NRo0JiALay44= -github.com/modelcontextprotocol/go-sdk v1.7.0/go.mod h1:dL7u98E/zjJTGzEq+j30jQ8K2k1mb6LeAH4inEcSGts= +github.com/modelcontextprotocol/go-sdk v1.8.0-pre.2 h1:Sxti6bD15KmHiTqcJ54nt9G6885m8DVwAxZX6Iu4Kjc= +github.com/modelcontextprotocol/go-sdk v1.8.0-pre.2/go.mod h1:dL7u98E/zjJTGzEq+j30jQ8K2k1mb6LeAH4inEcSGts= github.com/muesli/cancelreader v0.2.2 h1:3I4Kt4BQjOR54NavqnDogx/MIoWBFa0StPA8ELUXHmA= github.com/muesli/cancelreader v0.2.2/go.mod h1:3XuTXfFS2VjM+HTLZY9Ak0l6eUKfijIfMUZ4EgX0QYo= github.com/ncruces/go-strftime v1.0.0 h1:HMFp8mLCTPp341M/ZnA4qaf7ZlsbTc+miZjCLOFAw7w=