f2e83e7b9a
Co-authored-by: nova28 <17953305+nova28@users.noreply.github.com> Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com> Co-authored-by: Carlos Florencio <carlosmflorencio@gmail.com>
125 lines
5.3 KiB
Markdown
125 lines
5.3 KiB
Markdown
---
|
|
id: "03-evaluator"
|
|
title: "Pure classification evaluator"
|
|
status: done
|
|
wave: 3
|
|
depends_on: ["02-ledger-store"]
|
|
plan: "plan.md"
|
|
spec: "../../specs/task-delivery-ledger/spec.md"
|
|
---
|
|
|
|
# Task 03: Pure classification evaluator
|
|
|
|
One function, no database and no git:
|
|
|
|
```go
|
|
func Classify(obs Observation) Classification
|
|
```
|
|
|
|
`Observation` is the input struct defined in the plan's **`observe.go`** table
|
|
(task 04 populates it; define it here if task 04 has not landed, and task 04
|
|
consumes it as given). `Classification` carries `Outcome`, `DeliveryBasis`,
|
|
`DeliveryRef`, `ReachedDefaultAt`, `ReachedDefaultBasis`, `ReachedDefaultRef` and
|
|
`ObservedBranchCommits`.
|
|
|
|
Keeping this pure is the point: it makes the spec's entire Classification and
|
|
Squash-merge scenario set a table-driven unit test with no fixtures, no temp
|
|
database and no git.
|
|
|
|
## Rules
|
|
|
|
The spec's five rules in exactly this order, first match wins:
|
|
|
|
1. `pr_merge` — a merged, non-detached provider row exists. Basis
|
|
`provider_pr_merged`.
|
|
2. `direct_commit` — two or more distinct non-empty head commits on snapshots
|
|
whose `branch` equals the repository's `default_branch`. Basis
|
|
`default_branch_commit`.
|
|
3. `unknown` — commits observed on a non-default branch
|
|
(`MaxAhead > 0` or two or more distinct heads) and neither rule 1 nor 2
|
|
matched. Basis `reached_default_unattributed` when `reached_default_at` is
|
|
set, `branch_commits_unmerged` otherwise.
|
|
4. `no_delivery_observed` — at least one snapshot exists and every one shows
|
|
`ahead = 0` with a single distinct head commit. Basis `no_commits_observed`.
|
|
5. `unknown` — no snapshot and no provider row. Basis `no_observations`.
|
|
|
|
Rule 3 is deliberate, not a gap. The outcome enum is fixed at four values, so
|
|
"reached the default branch by a route nobody observed" is recorded in
|
|
`reached_default_at` / `reached_default_basis` rather than being forced into
|
|
`pr_merge` or `direct_commit`, either of which would assert a route that was not
|
|
observed.
|
|
|
|
Rules 4 and 5 must not collapse into each other: "we looked and there was
|
|
nothing" and "we never looked" are different facts, and `SnapshotCount == 0` is
|
|
what separates them.
|
|
|
|
## Default-branch observation
|
|
|
|
Computed here from three of the four bases: `provider_pr_merged` (a merged
|
|
provider row whose base branch equals the default branch),
|
|
`default_branch_commit`, and `ancestor_of_default` (task 05 supplies the boolean;
|
|
treat an absent probe as no evidence). `push_webhook_default` is in the
|
|
vocabulary but is never produced by this card — the webhook subscriber is
|
|
explicitly out of scope.
|
|
|
|
When `obs.DefaultBranch == ""`, rule 2 and the default-branch observation are
|
|
both skipped and the basis records `default_branch_unknown`. Classification still
|
|
falls through to rules 3-5; it does not error.
|
|
|
|
- **Acceptance:**
|
|
1. Every Classification scenario in the spec has a corresponding table case
|
|
and passes, including the rule-4 / rule-5 split and the
|
|
`default_branch_unknown` fallthrough.
|
|
2. A negative or absent ancestry result produces no `reached_default_at` and
|
|
does not change the outcome.
|
|
3. `Classify` performs no I/O: it takes no `context.Context`, no `*sqlx.DB` and
|
|
no `exec.Cmd`.
|
|
|
|
- **Verification:**
|
|
`cd apps/backend && go test -run TestClassify ./internal/delivery/... && make lint`
|
|
|
|
- **Files likely touched:**
|
|
- `apps/backend/internal/delivery/evaluator.go`
|
|
- `apps/backend/internal/delivery/evaluator_test.go`
|
|
- `apps/backend/internal/delivery/models.go` (add `Observation` /
|
|
`Classification` if task 04 has not already)
|
|
|
|
- **Dependencies:** Task 02 (vocabularies and `rank`).
|
|
|
|
- **Parallelism:** parallel-safe with task 04 — different files in the same
|
|
package, no shared schema or migration. Coordinate only on the `Observation`
|
|
struct: whichever task lands first defines it.
|
|
|
|
- **Inputs:** Spec **Classification**, **Default-branch observation**,
|
|
**Failure modes**, and the **Classification** + **Squash-merge and negative
|
|
evidence** scenarios.
|
|
|
|
- **Output contract:** summary, files changed, tests run with counts, blockers,
|
|
risks, and task/plan status update in the same conversation.
|
|
|
|
## Results
|
|
|
|
**Files changed:** `internal/delivery/evaluator.go`, `internal/delivery/evaluator_test.go`
|
|
(table-driven `TestClassify*` cases), `internal/delivery/models.go`
|
|
(`Observation` / `Classification` types, shared with task 04).
|
|
|
|
**Commands run:**
|
|
- `cd apps/backend && go test -run TestClassify ./internal/delivery/...` →
|
|
`ok`, 25 subtests pass, 0 fail — covers the rule-4/rule-5 split, the
|
|
`default_branch_unknown` fallthrough (rules 3-5 still evaluated), and the
|
|
squash-merge / negative-evidence scenarios.
|
|
- `make lint` — clean.
|
|
|
|
**Acceptance verification:** #1 (every spec Classification scenario has a
|
|
table case) and #2 (negative/absent ancestry produces no
|
|
`reached_default_at` and does not change the outcome) are covered by the
|
|
`TestClassify*` table cases above. #3 (`Classify` performs no I/O) verified
|
|
by reading `evaluator.go`'s `Classify` signature directly — it takes an
|
|
`Observation` value and returns a `Classification` value; no
|
|
`context.Context`, `*sqlx.DB`, or `exec.Cmd` appears anywhere in the
|
|
function or its call graph within this file.
|
|
|
|
**Security/trust and external side-effects:** None — `Classify` is pure
|
|
computation over already-fetched data.
|
|
applicable, or explicitly state `None`.
|