feat(app): resolve recorded search hits to their exact targets

Map every recorded search hit payload (pipeline, version, run, step,
field, artifact) to the server's own target token and accept that
token back, so a result can name the exact entity it opened. A hit
whose payload or recorded token is incomplete or disagreeing is
reported as unresolved rather than guessed.
This commit is contained in:
2026-10-22 02:18:44 +01:00
parent 8cfc4443df
commit cbba026cdc
2 changed files with 528 additions and 0 deletions
@@ -0,0 +1,310 @@
import '../../../core/api_gateway.dart';
/// The kind of recorded entity a resolved target names.
enum SearchTargetKind { pipeline, version, run, step, field, artifact }
/// The exact identity behind a recorded search hit.
///
/// [wire] is the server's own stable target token
/// (`internal/protocol/search.go`): `pipeline:<id>`, `pipeline:<id>:v<version>`,
/// `run:<id>`, `run:<id>:<sequence>`, `run:<id>:<sequence>:<field>` or the
/// recorded artifact URL. It is derived from the typed payload, never copied
/// from the hit, and [SearchTarget.fromWire] accepts it back.
///
/// The token is the identity: two targets that serialise to the same token are
/// the same target even when one of them also carries recorded visit facts the
/// token does not encode. A hit without an identity in its payload is reported
/// as [UnresolvedSearchTarget] by [searchTargetFor]; the client never guesses.
sealed class SearchTarget {
const SearchTarget();
SearchTargetKind get kind;
/// The server's target token for this identity.
String get wire;
/// Parses a server target token, or null when it names no known target.
///
/// A token carries only identity, so a parsed step or artifact target has no
/// recorded stage/visit facts; those are payload extras, not identity.
static SearchTarget? fromWire(String wire) {
final token = wire.trim();
if (token.isEmpty) return null;
final pipeline = RegExp(
r'^pipeline:([0-9]+)(?::v([0-9]+))?$',
).firstMatch(token);
if (pipeline != null) {
final id = _positive(pipeline.group(1));
if (id == null) return null;
final version = pipeline.group(2);
if (version == null) return SearchPipelineTarget(id);
final parsed = _positive(version);
return parsed == null ? null : SearchVersionTarget(id, parsed);
}
final run = RegExp(r'^run:([0-9]+)(?::(.+))?$').firstMatch(token);
if (run != null) {
final runId = _positive(run.group(1));
if (runId == null) return null;
final rest = run.group(2);
if (rest == null) return SearchRunTarget(runId);
final parts = rest.split(':');
if (parts.length > 2) return null;
final sequence = _positive(parts.first);
if (sequence == null) return null;
if (parts.length == 1) return SearchStepTarget(runId, sequence);
final field = parts.last;
return field.trim().isEmpty
? null
: SearchFieldTarget(runId, sequence, field);
}
// The server's artifact target is its own relative file URL
// (`/artifacts/<run>/<step>/<name>`); an absolute form is accepted only when
// it carries that same path.
if (token.startsWith('/artifacts/')) return SearchArtifactTarget(token);
if (token.startsWith('http://') || token.startsWith('https://')) {
final uri = Uri.tryParse(token);
if (uri != null && uri.path.startsWith('/artifacts/')) {
return SearchArtifactTarget(token);
}
}
return null;
}
@override
bool operator ==(Object other) => other is SearchTarget && other.wire == wire;
@override
int get hashCode => wire.hashCode;
@override
String toString() => wire;
}
/// A pipeline identity hit: the pipeline's detail, always at its latest version.
final class SearchPipelineTarget extends SearchTarget {
const SearchPipelineTarget(this.pipelineId);
final int pipelineId;
@override
SearchTargetKind get kind => SearchTargetKind.pipeline;
@override
String get wire => 'pipeline:$pipelineId';
}
/// A pipeline version hit: one exact recorded definition.
final class SearchVersionTarget extends SearchTarget {
const SearchVersionTarget(this.pipelineId, this.version);
final int pipelineId;
final int version;
@override
SearchTargetKind get kind => SearchTargetKind.version;
@override
String get wire => 'pipeline:$pipelineId:v$version';
}
/// A run identity hit.
final class SearchRunTarget extends SearchTarget {
const SearchRunTarget(this.runId);
final int runId;
@override
SearchTargetKind get kind => SearchTargetKind.run;
@override
String get wire => 'run:$runId';
}
/// A recorded step/visit hit. [stage] and [visit] are the visit facts the
/// payload records ([visit] is the server's visit number, not the zero-based
/// pane index); the server's token only names the run and sequence.
final class SearchStepTarget extends SearchTarget {
const SearchStepTarget(this.runId, this.sequence, {this.stage, this.visit});
final int runId;
final int sequence;
final String? stage;
final int? visit;
@override
SearchTargetKind get kind => SearchTargetKind.step;
@override
String get wire => 'run:$runId:$sequence';
}
/// A text hit inside one recorded step field.
final class SearchFieldTarget extends SearchTarget {
const SearchFieldTarget(this.runId, this.sequence, this.field);
final int runId;
final int sequence;
final String field;
@override
SearchTargetKind get kind => SearchTargetKind.field;
@override
String get wire => 'run:$runId:$sequence:$field';
}
/// A recorded artifact hit. The recorded URL is the identity; [runId] and
/// [sequence] locate the visit that produced it.
final class SearchArtifactTarget extends SearchTarget {
const SearchArtifactTarget(this.url, {this.runId, this.sequence});
final String url;
final int? runId;
final int? sequence;
@override
SearchTargetKind get kind => SearchTargetKind.artifact;
@override
String get wire => url;
}
/// Either the exact [SearchTarget] a hit names, or the reason it names none.
sealed class SearchTargetResolution {
const SearchTargetResolution();
}
final class ResolvedSearchTarget extends SearchTargetResolution {
const ResolvedSearchTarget(this.target);
final SearchTarget target;
}
final class UnresolvedSearchTarget extends SearchTargetResolution {
const UnresolvedSearchTarget(this.reason);
/// Why the hit cannot be resolved, for the caller's own reporting. It is not
/// operator-facing copy.
final String reason;
}
/// Maps the typed payload of one recorded search hit to its exact identity.
///
/// Payload keys are checked in the same order as the landed row model, so a hit
/// resolves to the target its visible row describes. The server's recorded
/// token must also be present and equal the serialised identity: a hit without
/// a token is unresolvable, consistent with the landed row model marking such a
/// row read-only, and a token that disagrees with its payload is refused rather
/// than guessed. Unknown payloads, and a payload missing any part of its
/// identity (an id, a sequence, a field name or an artifact URL), are
/// [UnresolvedSearchTarget].
SearchTargetResolution searchTargetFor(JsonMap hit) {
final identity = _identityFor(hit);
if (identity is UnresolvedSearchTarget) return identity;
final target = (identity as ResolvedSearchTarget).target;
final recorded = _text(hit['target']);
if (recorded == null) {
return const UnresolvedSearchTarget('recorded target is missing');
}
if (recorded != target.wire) {
return const UnresolvedSearchTarget(
'recorded target does not match its payload',
);
}
return ResolvedSearchTarget(target);
}
SearchTargetResolution _identityFor(JsonMap hit) {
final pipeline = _payload(hit, 'pipeline');
if (pipeline != null) {
final id = _positive(pipeline['id']);
if (id == null) {
return const UnresolvedSearchTarget('pipeline identity is missing');
}
return ResolvedSearchTarget(SearchPipelineTarget(id));
}
final version = _payload(hit, 'version');
if (version != null) {
final pipelineId = _positive(version['pipeline_id']);
final number = _positive(version['version']);
if (pipelineId == null || number == null) {
return const UnresolvedSearchTarget('version identity is incomplete');
}
return ResolvedSearchTarget(SearchVersionTarget(pipelineId, number));
}
final run = _payload(hit, 'run');
if (run != null) {
final id = _positive(run['id']);
if (id == null) {
return const UnresolvedSearchTarget('run identity is missing');
}
return ResolvedSearchTarget(SearchRunTarget(id));
}
final step = _payload(hit, 'step');
if (step != null) {
final runId = _positive(step['run_id']);
final sequence = _positive(step['sequence']);
if (runId == null || sequence == null) {
return const UnresolvedSearchTarget('step identity is incomplete');
}
final visit = _positive(step['visit']);
final stage = _text(step['stage']);
return ResolvedSearchTarget(
SearchStepTarget(runId, sequence, stage: stage, visit: visit),
);
}
final field = _payload(hit, 'field');
if (field != null) {
final runId = _positive(field['run_id']);
final sequence = _positive(field['sequence']);
final name = _text(field['field']);
if (runId == null || sequence == null || name == null) {
return const UnresolvedSearchTarget('field identity is incomplete');
}
return ResolvedSearchTarget(SearchFieldTarget(runId, sequence, name));
}
final artifact = _payload(hit, 'artifact');
if (artifact != null) {
final url = _text(artifact['url']);
if (url == null) {
return const UnresolvedSearchTarget('artifact url is missing');
}
return ResolvedSearchTarget(
SearchArtifactTarget(
url,
runId: _positive(artifact['run_id']),
sequence: _positive(artifact['sequence']),
),
);
}
return const UnresolvedSearchTarget('no recorded target payload');
}
Map<String, dynamic>? _payload(JsonMap hit, String key) {
final value = hit[key];
return value is Map ? Map<String, dynamic>.from(value) : null;
}
int? _positive(Object? value) {
final number = value is int
? value
: value is num
? value.toInt()
: int.tryParse('${value ?? ''}');
return number != null && number > 0 ? number : null;
}
String? _text(Object? value) {
final text = '${value ?? ''}';
return text.trim().isEmpty ? null : text;
}
@@ -0,0 +1,218 @@
import 'package:flutter_test/flutter_test.dart';
import 'package:pipelines_app/core/api_gateway.dart';
import 'package:pipelines_app/features/search/domain/search_target.dart';
JsonMap pipelineHit([JsonMap overrides = const {}]) => {
'kind': 'pipeline',
'target': 'pipeline:7',
'pipeline': {
'id': 7,
'name': 'release',
'version': 3,
'stages': 4,
...overrides,
},
};
JsonMap versionHit([JsonMap overrides = const {}]) => {
'kind': 'version',
'target': 'pipeline:9:v2',
'version': {
'pipeline_id': 9,
'version': 2,
'content_hash': 'abc',
'created_at': '2026-01-01T00:00:00Z',
...overrides,
},
};
JsonMap runHit([JsonMap overrides = const {}]) => {
'kind': 'run',
'target': 'run:11',
'run': {
'id': 11,
'pipeline_name': 'release',
'status': 'succeeded',
...overrides,
},
};
JsonMap stepHit([JsonMap overrides = const {}]) => {
'kind': 'step',
'target': 'run:11:4',
'step': {
'run_id': 11,
'sequence': 4,
'stage': 'builder',
'visit': 2,
'outcome': 'success',
...overrides,
},
};
JsonMap fieldHit([JsonMap overrides = const {}]) => {
'kind': 'field',
'target': 'run:11:4:output',
'matched_field': 'output',
'field': {
'run_id': 11,
'sequence': 4,
'field': 'output',
'snippet': 'the release is ready',
...overrides,
},
};
JsonMap artifactHit([JsonMap overrides = const {}]) => {
'kind': 'artifact',
'target': '/artifacts/11/4/notes.md',
'artifact': {
'run_id': 11,
'sequence': 4,
'name': 'notes.md',
'content_type': 'text/markdown',
'size_bytes': 2048,
'url': '/artifacts/11/4/notes.md',
...overrides,
},
};
SearchTarget resolved(JsonMap hit) {
final resolution = searchTargetFor(hit);
expect(resolution, isA<ResolvedSearchTarget>(), reason: '$hit');
return (resolution as ResolvedSearchTarget).target;
}
UnresolvedSearchTarget unresolved(JsonMap hit) {
final resolution = searchTargetFor(hit);
expect(resolution, isA<UnresolvedSearchTarget>(), reason: '$hit');
return resolution as UnresolvedSearchTarget;
}
void main() {
test('every recorded hit kind serialises back to its server token', () {
final pipeline = resolved(pipelineHit());
expect(pipeline, isA<SearchPipelineTarget>());
expect((pipeline as SearchPipelineTarget).pipelineId, 7);
expect(pipeline.kind, SearchTargetKind.pipeline);
expect(pipeline.wire, pipelineHit()['target']);
final version = resolved(versionHit());
expect(version, isA<SearchVersionTarget>());
expect((version as SearchVersionTarget).pipelineId, 9);
expect(version.version, 2);
expect(version.wire, versionHit()['target']);
final run = resolved(runHit());
expect(run, isA<SearchRunTarget>());
expect((run as SearchRunTarget).runId, 11);
expect(run.wire, runHit()['target']);
final step = resolved(stepHit());
expect(step, isA<SearchStepTarget>());
expect((step as SearchStepTarget).runId, 11);
expect(step.sequence, 4);
expect(step.stage, 'builder');
expect(step.visit, 2);
expect(step.wire, stepHit()['target']);
final field = resolved(fieldHit());
expect(field, isA<SearchFieldTarget>());
expect((field as SearchFieldTarget).runId, 11);
expect(field.sequence, 4);
expect(field.field, 'output');
expect(field.wire, fieldHit()['target']);
final artifact = resolved(artifactHit());
expect(artifact, isA<SearchArtifactTarget>());
expect((artifact as SearchArtifactTarget).url, '/artifacts/11/4/notes.md');
expect(artifact.runId, 11);
expect(artifact.sequence, 4);
expect(artifact.wire, artifactHit()['target']);
});
test('a payload without its identity is reported as unresolvable', () {
expect(unresolved({}).reason, 'no recorded target payload');
expect(unresolved(pipelineHit({'id': null})).reason, contains('pipeline'));
expect(
unresolved(versionHit({'pipeline_id': 9, 'version': 0})).reason,
contains('version'),
);
expect(unresolved(runHit({'id': 0})).reason, contains('run'));
expect(
unresolved(stepHit({'run_id': 11, 'sequence': 0})).reason,
contains('step'),
);
expect(
unresolved(fieldHit({'run_id': 11, 'sequence': 4, 'field': ' '})).reason,
contains('field'),
);
expect(unresolved(artifactHit({'url': ' '})).reason, contains('artifact'));
expect(
unresolved({'kind': 'future_kind', 'target': 'widget:7'}).reason,
'no recorded target payload',
);
});
test('a hit without a matching recorded token is unresolvable', () {
expect(
unresolved({
'kind': 'run',
'run': {'id': 11},
}).reason,
'recorded target is missing',
);
expect(
unresolved({...pipelineHit(), 'target': 'pipeline:8'}).reason,
contains('does not match'),
);
expect(
unresolved({...stepHit(), 'target': 'run:11:5'}).reason,
contains('does not match'),
);
});
test('a serialised target parses back to the same identity', () {
final targets = <SearchTarget>[
resolved(pipelineHit()),
resolved(versionHit()),
resolved(runHit()),
resolved(stepHit()),
resolved(fieldHit()),
resolved(artifactHit()),
];
for (final target in targets) {
final parsed = SearchTarget.fromWire(target.wire);
expect(parsed, target, reason: target.wire);
expect(parsed!.wire, target.wire, reason: target.wire);
}
// The token names the visit's run and sequence, not its stage/visit facts.
final step = resolved(stepHit()) as SearchStepTarget;
final parsed = SearchTarget.fromWire(step.wire) as SearchStepTarget;
expect(parsed, step);
expect(parsed.stage, isNull);
expect(parsed.visit, isNull);
});
test('a token outside the server vocabulary names no target', () {
for (final token in const [
'',
' ',
'widget:7',
'pipeline:0',
'pipeline:7:v0',
'run:11:0',
'run:11:4:',
'http://example.test/not-an-artifact',
]) {
expect(SearchTarget.fromWire(token), isNull, reason: token);
}
expect(SearchTarget.fromWire('run:11'), const SearchRunTarget(11));
expect(
SearchTarget.fromWire('pipeline:7:v2'),
const SearchVersionTarget(7, 2),
);
expect(SearchTarget.fromWire('pipeline:7'), const SearchPipelineTarget(7));
});
}