@@ -12,7 +12,8 @@ export const examples: Example[] = [
1212import * as clack from "@clack/prompts" ;
1313import { type ItemType } from "@hyperframes/core" ;
1414import { c } from "../ui/colors.js" ;
15- import { listRegistryItems , loadAllItems } from "../registry/resolver.js" ;
15+ import { loadAllItems } from "../registry/resolver.js" ;
16+ import { fetchRegistryManifest } from "../registry/remote.js" ;
1617import { loadProjectConfig , DEFAULT_PROJECT_CONFIG } from "../utils/projectConfig.js" ;
1718import { resolve } from "node:path" ;
1819import { finishCommand } from "../utils/commandResult.js" ;
@@ -21,12 +22,14 @@ import { searchByWords } from "../registry/localSearch.js";
2122import {
2223 downloadOfferMessage ,
2324 ensureLocalModel ,
25+ type LocalModelStatus ,
2426 localModelStatus ,
2527 nonInteractiveConsentMessage ,
2628 recordLocalModelConsent ,
2729} from "../registry/localModel.js" ;
2830import { localRuntimeAvailable } from "../registry/localEmbedder.js" ;
2931import {
32+ cachedLocalVectorRevision ,
3033 fetchLocalVectors ,
3134 hasLocalVectors ,
3235 localSemanticRanking ,
@@ -46,17 +49,19 @@ import {
4649// fallow-ignore-next-line complexity
4750async function prepareOnDeviceTier ( opts : {
4851 assumedYes : boolean ;
52+ artifactRevision ?: string ;
4953 canPrompt : boolean ;
5054 registry : string ;
5155 registryNames : ReadonlySet < string > ;
56+ status : LocalModelStatus ;
5257} ) : Promise < string [ ] > {
5358 const warnings : string [ ] = [ ] ;
5459 const warn = ( message : string ) : void => {
5560 warnings . push ( message ) ;
5661 console . error ( message ) ;
5762 } ;
5863
59- const status = localModelStatus ( ) ;
64+ const status = opts . status ;
6065 if ( ! opts . assumedYes && status . status === "declined" ) {
6166 warn (
6267 "on-device search skipped: the model download was previously declined. Re-run with --yes to consent." ,
@@ -99,14 +104,14 @@ async function prepareOnDeviceTier(opts: {
99104 recordLocalModelConsent ( true ) ;
100105 }
101106 const model = await ensureLocalModel ( ) ;
102- // The vectors are fetched once and nothing ever invalidates them, so an index
103- // that no longer covers the registry is the same situation as one that is not
104- // there at all: meaning search cannot reach part of the catalog. Both take the
105- // path this flag already takes. Deciding it costs a local read of the
106- // artifact's own name list; the only fetch is the one --on-device already
107- // performs when the vectors are absent.
108- if ( ! hasLocalVectors ( ) || countUnindexed ( opts . registryNames , localVectorNames ( ) ) > 0 ) {
109- await fetchLocalVectors ( opts . registry ) ;
107+ const revisionStale =
108+ opts . artifactRevision !== undefined && cachedLocalVectorRevision ( ) !== opts . artifactRevision ;
109+ if (
110+ ! hasLocalVectors ( ) ||
111+ revisionStale ||
112+ countUnindexed ( opts . registryNames , localVectorNames ( ) ) > 0
113+ ) {
114+ await fetchLocalVectors ( opts . registry , { expectedRevision : opts . artifactRevision } ) ;
110115 }
111116 // Deliberately not the fetch's own answer. A refresh that fails still leaves
112117 // the previous vectors on disk, and those still rank: reporting the tier
@@ -117,6 +122,11 @@ async function prepareOnDeviceTier(opts: {
117122 warn (
118123 `on-device search unavailable: ${ ! model ? "model" : "catalog vectors" } could not be fetched` ,
119124 ) ;
125+ } else if (
126+ opts . artifactRevision !== undefined &&
127+ cachedLocalVectorRevision ( ) !== opts . artifactRevision
128+ ) {
129+ warn ( "on-device search is using the previous catalog vectors because the update failed" ) ;
120130 }
121131 return warnings ;
122132}
@@ -178,11 +188,11 @@ export default defineCommand({
178188 finishCommand ( 1 ) ;
179189 }
180190
181- // Asked for unnarrowed on purpose. `listRegistryItems` filters the same
182- // in-memory manifest either way, so the whole list costs no extra fetch,
183- // and its names are the only honest definition of "in this registry" once
184- // the user's own --type/--tag has narrowed what gets loaded.
185- const entries = await listRegistryItems ( undefined , { baseUrl : config . registry } ) ;
191+ // Asked for the whole manifest on purpose: its item list defines coverage,
192+ // and its artifact revision is the one owner of vector freshness.
193+ const manifest = await fetchRegistryManifest ( config . registry ) ;
194+ const entries = manifest ?. items ?? [ ] ;
195+ const artifactRevision = manifest ?. catalogArtifact ?. revision ;
186196 const catalog = entries . filter ( ( e ) => e . type !== "hyperframes:example" ) ;
187197 const registryNames = new Set ( catalog . map ( ( e ) => e . name ) ) ;
188198 const filtered = typeFilter ? catalog . filter ( ( e ) => e . type === typeFilter ) : catalog ;
@@ -204,16 +214,31 @@ export default defineCommand({
204214 // Collected rather than only printed, so --json can carry the same reasons
205215 // the terminal shows. A machine that asked for a tier deserves to be told
206216 // it did not run.
207- const warnings =
208- query && args [ "on-device" ] === true
209- ? await prepareOnDeviceTier ( {
210- assumedYes : args . yes === true ,
211- canPrompt : process . stdout . isTTY === true && ! json ,
212- registry : config . registry ,
213- registryNames,
214- } )
215- : [ ] ;
216- const searched = query ? await applySearch ( tagged , query , registryNames ) : null ;
217+ const searchContext = query ? { status : localModelStatus ( ) } : null ;
218+ const routineUpdate =
219+ searchContext ?. status . status === "unavailable" ||
220+ ( searchContext ?. status . status === "ready" &&
221+ artifactRevision !== undefined &&
222+ cachedLocalVectorRevision ( ) !== artifactRevision ) ;
223+ const shouldPrepare = args [ "on-device" ] === true || routineUpdate ;
224+ let warnings : string [ ] = [ ] ;
225+ let effectiveStatus = searchContext ?. status ;
226+ if ( searchContext && shouldPrepare ) {
227+ warnings = await prepareOnDeviceTier ( {
228+ assumedYes : args . yes === true ,
229+ artifactRevision,
230+ canPrompt : process . stdout . isTTY === true && ! json ,
231+ registry : config . registry ,
232+ registryNames,
233+ status : searchContext . status ,
234+ } ) ;
235+ // A successful preparation can move not-asked/unavailable to ready. Read
236+ // the state owner again rather than carrying the pre-download snapshot.
237+ effectiveStatus = localModelStatus ( ) ;
238+ }
239+ const searched = effectiveStatus
240+ ? await applySearch ( tagged , query , registryNames , effectiveStatus )
241+ : null ;
217242 if ( searched ) warnings . push ( ...searched . warnings ) ;
218243 const matching = searched ? searched . items : tagged ;
219244
@@ -250,7 +275,7 @@ export default defineCommand({
250275 ] . filter ( Boolean ) ;
251276 console . log ( `No items match ${ criteria . join ( " and " ) } .` ) ;
252277 }
253- if ( query ) await offerLocalModel ( 0 , json , config . registry ) ;
278+ if ( query ) await offerLocalModel ( 0 , json , config . registry , artifactRevision ) ;
254279 return ;
255280 }
256281
@@ -322,7 +347,7 @@ export default defineCommand({
322347 // reads as the tool arguing with itself.
323348 if ( warnings . length === 0 ) {
324349 reportLocalModelOption ( json ) ;
325- await offerLocalModel ( matching . length , json , config . registry ) ;
350+ await offerLocalModel ( matching . length , json , config . registry , artifactRevision ) ;
326351 }
327352 }
328353 }
@@ -465,11 +490,16 @@ interface SearchOutcome<T> {
465490
466491async function applySearch <
467492 T extends { name : string ; title : string ; description : string ; tags ?: string [ ] } ,
468- > ( items : T [ ] , query : string , registryNames : ReadonlySet < string > ) : Promise < SearchOutcome < T > > {
493+ > (
494+ items : T [ ] ,
495+ query : string ,
496+ registryNames : ReadonlySet < string > ,
497+ status : LocalModelStatus ,
498+ ) : Promise < SearchOutcome < T > > {
469499 const warnings : string [ ] = [ ] ;
470500 // On-device meaning search, when the user opted into the model. Free and
471501 // offline, and it answers phrasings word matching cannot reach.
472- if ( localModelStatus ( ) . status === "ready" ) {
502+ if ( status . status === "ready" ) {
473503 try {
474504 const ranking = await localSemanticRanking ( query ) ;
475505 if ( ranking ) {
@@ -554,6 +584,7 @@ async function offerLocalModel(
554584 matchCount : number ,
555585 json : boolean ,
556586 registryBaseUrl : string ,
587+ artifactRevision ?: string ,
557588) : Promise < void > {
558589 if ( json || ! process . stdout . isTTY ) return ;
559590 if ( localModelStatus ( ) . status !== "not-asked" ) return ;
@@ -573,7 +604,9 @@ async function offerLocalModel(
573604 // The vectors come from the registry rather than the package, so consent is
574605 // also the moment to fetch them. A failure here is reported: the alternative
575606 // is an offline tier the user turned on that silently never ranks anything.
576- const vectors = hasLocalVectors ( ) || ( await fetchLocalVectors ( registryBaseUrl ) ) ;
607+ const vectors =
608+ hasLocalVectors ( ) ||
609+ ( await fetchLocalVectors ( registryBaseUrl , { expectedRevision : artifactRevision } ) ) ;
577610 console . log (
578611 c . dim (
579612 vectors
0 commit comments