241 lines
No EOL
10 KiB
Markdown
241 lines
No EOL
10 KiB
Markdown
# Task 1 Ambiguity Handoff Addendum
|
|
|
|
## Goal
|
|
|
|
Resolve the Task 1 blocker by moving ambiguous GitLab and SourceForge URL handling out of pure taxonomy heuristics and into provider-aware resolution.
|
|
|
|
## Problem Restatement
|
|
|
|
The blocker is not that the classifier is missing a few more path rules.
|
|
|
|
The blocker is that some provider-hosted URL shapes do not carry enough information to determine final install semantics from path shape alone.
|
|
|
|
Two cases are responsible for the review churn:
|
|
|
|
- GitLab deep paths where a segment may be either a subgroup slug or a resource-like segment
|
|
- SourceForge `files/.../download` paths where the same suffix can represent either a concrete file download or a folder-style endpoint
|
|
|
|
Trying to settle those cases in `resolve_query(...)` forces the code into a false choice:
|
|
|
|
- accept ambiguous inputs too early and misclassify them
|
|
- reject provider-owned inputs too early and lose useful context
|
|
|
|
## Design Decision
|
|
|
|
Adopt an ambiguity handoff model.
|
|
|
|
That means:
|
|
|
|
- the classifier remains authoritative only for cases it can determine with high confidence
|
|
- ambiguous provider-hosted inputs are preserved as provider-owned candidates rather than flattened into `Unsupported`
|
|
- provider adapters become the layer that decides whether an ambiguous input is:
|
|
- a supported repository or project source
|
|
- a supported exact download form
|
|
- a supported source with no installable artifact
|
|
- truly unsupported for that provider
|
|
|
|
## Contract Boundary
|
|
|
|
### Classification policy
|
|
|
|
The classifier should use a strict positive-matching contract.
|
|
|
|
Each input shape must land in exactly one of three buckets:
|
|
|
|
- accept as a definite supported source
|
|
- accept as an explicit provider-owned candidate
|
|
- reject as unsupported
|
|
|
|
This means the classifier should prefer a small allowlist of accepted shapes over an expanding catalog of bespoke rejection rules.
|
|
|
|
Negative rules are still allowed when needed to protect a known false-positive family, but they are defensive exceptions, not the main design strategy.
|
|
|
|
### Classification must do
|
|
|
|
- identify definite GitHub, GitLab, SourceForge, direct URL, and file inputs
|
|
- accept only explicitly enumerated concrete shapes or explicitly enumerated candidate shapes
|
|
- preserve canonical locator hints when they are certain
|
|
- preserve enough raw path context for later provider-specific disambiguation
|
|
- continue classifying concrete artifact URLs as `DirectUrl` when the classifier can say so confidently
|
|
|
|
### Classification must not do
|
|
|
|
- grow by accumulating one-off rejection rules for every unsupported provider page family
|
|
- guess whether a GitLab deep path is a subgroup path or a resource page when the path shape is ambiguous
|
|
- guess whether a SourceForge nested `files/.../download` path is a file or folder endpoint when the path shape is ambiguous
|
|
- perform provider-specific network discovery
|
|
|
|
### Resolver layer must do
|
|
|
|
- own final interpretation of ambiguous provider-hosted inputs
|
|
- return structured outcomes through the adapter contract
|
|
- keep `UnsupportedSource` reserved for sources the adapter genuinely does not own
|
|
- use `NoInstallableArtifact` for provider-owned inputs that are valid but not installable under current scope
|
|
|
|
## Proposed Source Model Adjustment
|
|
|
|
Introduce an explicit handoff shape for ambiguous provider-owned inputs.
|
|
|
|
The minimal acceptable form is:
|
|
|
|
- preserve the original locator
|
|
- preserve provider ownership
|
|
- preserve any canonical parts that are certain
|
|
- add a signal that provider resolution is still required before install semantics are known
|
|
|
|
This can be modeled either as:
|
|
|
|
1. a dedicated ambiguity marker on `SourceRef`
|
|
2. additional normalized kinds representing provider-owned unresolved candidates
|
|
|
|
The preferred direction is additional normalized kinds, because they keep the ambiguity visible in tests and logs without adding a free-form boolean that can drift.
|
|
|
|
Illustrative shapes:
|
|
|
|
- `NormalizedSourceKind::GitLabCandidate`
|
|
- `NormalizedSourceKind::SourceForgeCandidate`
|
|
|
|
The exact enum names are secondary. The important part is making unresolved provider ownership explicit.
|
|
|
|
## Provider Responsibilities
|
|
|
|
### GitLab
|
|
|
|
GitLab adapter logic should decide whether a GitLab-owned ambiguous input is:
|
|
|
|
- a valid repository locator
|
|
- a release-like source with concrete version semantics
|
|
- a provider-owned but non-installable resource page
|
|
- unsupported because it does not fit the adapter's supported contract
|
|
|
|
Initial scope should stay narrow:
|
|
|
|
- keep current definite repository and release-like support
|
|
- add only one or two ambiguous deep-path cases as a first expansion slice
|
|
- do not try to solve every GitLab resource URL family at once
|
|
|
|
### SourceForge
|
|
|
|
SourceForge adapter logic should decide whether a SourceForge-owned ambiguous input is:
|
|
|
|
- a concrete latest-download install source
|
|
- a concrete direct artifact URL
|
|
- a provider-owned project or folder view with no installable artifact
|
|
- unsupported for current source scope
|
|
|
|
Initial scope should stay narrow:
|
|
|
|
- keep bare project URLs as provider-owned and non-installable
|
|
- keep `files/latest/download` as the first concrete repository-backed install source
|
|
- add exactly one nested `files/.../download` ambiguity case to the adapter decision path
|
|
|
|
## Testing Strategy
|
|
|
|
The blocker should be resolved by shifting assertions to the right layer.
|
|
|
|
### Classification tests
|
|
|
|
Update `query_resolution` coverage so ambiguous cases assert provider ownership and handoff state instead of asserting final install semantics.
|
|
|
|
Coverage should be organized around accepted-shape allowlists:
|
|
|
|
- accepted concrete shapes
|
|
- accepted candidate shapes
|
|
- a small number of representative false-positive guards
|
|
|
|
Examples:
|
|
|
|
- a concrete SourceForge artifact download still classifies as `DirectUrl`
|
|
- a definite GitLab repository form still classifies as `GitLab`
|
|
- an ambiguous GitLab deep path becomes a GitLab-owned candidate, not `Unsupported`
|
|
- an ambiguous SourceForge nested download path becomes a SourceForge-owned candidate, not prematurely direct or unsupported
|
|
|
|
### Adapter contract tests
|
|
|
|
Add tests that assert adapters make the final decision for ambiguous handoff inputs.
|
|
|
|
Examples:
|
|
|
|
- GitLab candidate path resolves to supported repository semantics
|
|
- GitLab candidate path resolves to `NoInstallableArtifact`
|
|
- SourceForge candidate path resolves to `Resolved`
|
|
- SourceForge candidate path resolves to `NoInstallableArtifact`
|
|
|
|
### Install and failure tests
|
|
|
|
Keep install-flow tests focused on supported concrete outcomes.
|
|
|
|
Keep failure tests focused on the distinction between:
|
|
|
|
- unsupported query
|
|
- provider-owned source with no installable artifact
|
|
- runtime install or transport failure
|
|
|
|
## Incremental Execution Plan
|
|
|
|
### Phase 1: Lock the boundary
|
|
|
|
- update the design docs to state that classification only decides what it can know with certainty
|
|
- record that ambiguous provider-hosted inputs are a resolver concern
|
|
|
|
### Phase 2: Add handoff representation
|
|
|
|
- extend the source model with explicit provider-candidate semantics
|
|
- thread that representation through the query classifier
|
|
|
|
### Phase 3: Shift one GitLab ambiguity case
|
|
|
|
- add a failing classification test for an ambiguous GitLab deep path
|
|
- classify it as a GitLab-owned candidate
|
|
- add adapter contract coverage for the GitLab decision
|
|
|
|
### Phase 4: Shift one SourceForge ambiguity case
|
|
|
|
- add a failing classification test for a nested `files/.../download` ambiguity case
|
|
- classify it as a SourceForge-owned candidate
|
|
- add adapter contract coverage for the SourceForge decision
|
|
|
|
### Phase 5: Tighten error reporting
|
|
|
|
- make sure ambiguous provider-owned inputs that do not yield installable artifacts surface as `NoInstallableArtifact`
|
|
- avoid regressing them into unsupported-query failures
|
|
|
|
## Progress Update
|
|
|
|
Current implementation status in this branch:
|
|
|
|
- Phase 1 is complete. The classifier-versus-adapter boundary is now documented explicitly in this addendum.
|
|
- Phase 2 is complete. `GitLabCandidate` and `SourceForgeCandidate` now exist in the source model and are produced by classification for the narrow ambiguity cases under test.
|
|
- Phase 3 is complete for the first GitLab slice. `https://gitlab.com/<group>/<subgroup>/releases/<repo>` remains a classified candidate, but the GitLab adapter now resolves it as repository semantics with a derived canonical locator.
|
|
- Phase 4 is complete for two SourceForge slices. `https://sourceforge.net/projects/<project>/files/releases/stable/download` remains a classified candidate and now resolves as a provider-owned latest-download source. `https://sourceforge.net/projects/<project>/files/releases/v*/download` is now preserved as a provider-owned candidate and surfaces as `NoInstallableArtifact`.
|
|
- Phase 5 is partially complete. Provider-owned ambiguous inputs now distinguish unsupported-query failures from no-artifact outcomes, and both GitLab and SourceForge have at least one adapter-owned positive resolution path.
|
|
|
|
The current intended classifier contract is:
|
|
|
|
- accept explicit supported shapes
|
|
- accept explicit candidate shapes
|
|
- reject everything else
|
|
|
|
That contract is intentionally stricter than heuristic best-effort classification and intentionally narrower than provider resolution.
|
|
|
|
What remains intentionally out of scope for this slice:
|
|
|
|
- additional GitLab candidate families beyond the first repository-style deep path
|
|
- broader SourceForge folder and version-path families beyond the `releases/stable/download` and narrow `releases/v*/download` rules
|
|
- any network-backed provider discovery in classification
|
|
|
|
## Success Criteria
|
|
|
|
This blocker is considered resolved when:
|
|
|
|
- `query_resolution` no longer oscillates over ambiguous provider-owned shapes
|
|
- ambiguous provider-hosted URLs are no longer forced into final install semantics during classification
|
|
- adapters are the only place where ambiguous provider paths are interpreted fully
|
|
- failure reporting distinguishes unsupported inputs from provider-owned non-installable inputs
|
|
|
|
## Non-Goals
|
|
|
|
- solving every ambiguous GitLab deep-path variant in one pass
|
|
- solving every SourceForge nested folder or version path in one pass
|
|
- introducing network discovery into the pure query classifier
|
|
- expanding current supported source scope beyond what the adapter tests can defend clearly |